Power CD-ROM!! 8/Power CD-ROM 8.iso/prgmming/dbtalk/dbtalk.doc

Text File | 1993-06-09 | 121.4 KB | 4,748 lines

@@Set-up

The Installation program should create a structure
that looks like this :

DBTALK ---+----- BIN
          |
          +----- LIB
          |
          +----- RESOURCE
          |
          +----- SOURCE
          |
          +----- DEMO

The BIN subdirectory contains all EXE files and the
run-time engines. It includes batch files (ED.BAT,
COMP.BAT and MAKE.BAT) to use DBTALK for program
compilation and resource linking. For Example :

ED laser.prg

ED laser.res

COMP laser

MAKE laser

The LIB subdirectory contains all external Classes and
user-defined Classes.

The RESOURCE subdirectory contains all resources, SCN
, VEW, ICN, FNT, PAL, ARR, BMP, VEC and TXT files.

The SOURCE subdirectory contains the source code for
all applications.

The DEMO subdirectory is an example of an application
subdirectory. Each DBTALK application should have a
subdirectory in which it will run. It will contain the
database files etc...

@@ SET variables

In order to use the system, three SET variables must
be defined in your environment.

1. You have to declare a DOS Set variable called
    'PLL' which points to the   directory in which you
    have installed DBTALK binary code. You can put the
    SET statement into your AUTOEXEC.BAT file or any
    BAT file you wish to use to activate DBTALK.

    For example :

    SET PLL=C:\DBTALK\BIN

2. You have to include the DBTALK subdirectory in the
    PATH statement of your AUTOEXEC file.

    For example :

    PATH C:\;C:\DOS;C:\DBTALK

3. You have to declare a DOS Set variable called
    'ADL' which points to the   directory in which you
    have installed DBTALK resources. You can put the
    SET statement into your AUTOEXEC.BAT file or any
    BAT file you wish to use to activate DBTALK.

     For example :

     SET ADL=C:\DBTALK\RESOURCE

@@ Compiler

DB-TALK Resource Compiler

The DB-TALK resource compiler is the means of
converting all the defined resources including the
code into an EXE file.

To use the compiler type the following from your DOS
prompt:

C:\DBTALK\DEMO> DBTALK <resource file> [switches]

<resource file> is the source file containing resource
statements or program functions.

Although the file may contain both code and resource
information, in order to generate different EXE files
for different environments from the same code, it is
recommended that source code should be put in '.PRG'
files and resources into '.RES' files. By using the
EXTERNAL resource directive and the /o switch,
compiled code can be assembled into the EXE  over and
over without re-compiling.

[switches] are as follows:

/O - Create an External reusable ADL file.

/A - Use Advanced run-time engine. This includes
      Clipper GET and TBROWSE sub-systems.

     The default is the simpler GFORCE GET and BROWSE
      functions. This run-time engine requires 50K
      less of memory than the advanced run-time
      engine.

/T - Use VGA font re-definition in text mode. This
      gives the best memory usage at the expense of
      VGA graphics. Most screen resources like buttons
      and fonts are supported, but there is a 25-line
      limitation and no graphic objects like bitmaps
      and vector graphics. All new font files must be
      cloned from the supplied files.

@@ Debugging

The SetTrace(<lOn/lOff) function can be used to set
on/off TRACING and be used to trace specific programs
sections during debugging.

Each generated Application creates a file called
'DBTALK.LOG' in the directory from where it is
invoked. This file will contain any error messages
that occur during the run.

In addition, valuable trace information will be
written to this file when TRACING is set on.

A DOS set variable call ADLTRACE can be used for
global tracing without    re-compiling the program.
Just issue :

              C:\>SET adltrace=YES

to activate tracing and other value to disable.

To write to this file from an application, use
function LOGF(cText). For example :

            LogF('The value of cName is '+cName)

There is a simple debugger for DBTALK with limited
debugging facility available.

While tracing is on, pressing ALT D during a wait
state to break into an application and invoke the
debugger.

DBTALK will display the '>>' prompt on the message
line (line 24). Any valid expression can be entered at
this point. Variable values can be inspected and
modified with care. In graphics mode, it might be
preferable to write to the log file instead of the
screen.

It is also invoked automatically when an error occurs
and SETRACE is on.

Type EXIT or QUIT to exit the application.

Type RESUME to retry the error after a corection to
resume normal processing.

@@Introduction

Introduction

It is a well known fact that more effort is spent on
software maintenance, the process of modifying a
system after it has been handed over to a customer
than on the development of the software itself.

Many software developers know that what stops them
from producing application systems as fast as Stephen
King publishes novels is not their skills or the lack
of it but the effort to maintain concurrently all
versions of the applications they have already
produced.

Here are some of the reasons why every software
constructed goes through maintenance.

1.The software developer may have made errors which
   are only are discovered when the system is being
   used by customer with real-life data.

2.The customer's technology might have changed, for
   example, new version of the operating system, or
   the hardware may have been upgraded.

3.The customer requirements for the software system
   change over time even from the time the
   specification is frozen.

It is the last reason of changes in requirements that
is the most difficult to cope with. All developers
know that users never know what they really want.
Users often feel that their views and knowledge of
their systems are changing as they learn and think
more about it. As a result, they are usually half-way
up a learning curve when the system's specifications
are frozen.

Systems developed using structured ideas tend to
behave badly with respect with to change. Make no
mistake about it, structured systems when done
properly have been shown to meet user's requirement.
The problem is that the structure degrades as time
goes by, and each further change take another bash at
the structure of the system making it progressively
more difficult to apply changes, soaking more and more
skilled resource until the point comes when the
software has to be replaced and the whole cycle starts
all over again.

Object-oriented software development (OOD) techniques
focus on the objects in the system. At the beginning
of an OOD, an analyst will ask the customer what
entities are important in the system to be developed.

For example, in an invoicing system two important
entities are Customers and Invoices. After this the
analyst will investigate what operations affect these
entities. For example, a new Invoice will be created
when a customer makes a purchase and deleted or
archived when the customer fully pays up.

These entities are modelled into objects and then
implemented in an object-oriented programming
language. A number of these languages have been
implemented to industry quality standards. Such
languages enable a developer to define the data and
operations that manipulate them and implement them
using a facility known as a class. One of the most
popular of the these languages is C++.

Early experience with such languages have shown that
systems built with them tend to be much easier to
maintain but not faster to develop the first time
around. However they degrade at much slower rate than
applications developed with a structured approach.
Their selling point is that they offer a huge scope
for software re-usability.

Most, if not all computer users, end users and
programmers alike, are going to be affected by
object-orientation over the next decade.  For the end
user, this should make life easier, since it is via
graphical user interfaces (GUIs) that they will
encounter object-orientation.  The phenomenal success
of Microsoft Windows 3.1 is an indication that this
objective is already beginning to be realised.

For the programmer, life may be less simple, at least
initially.  Object orientation requires a change of
thinking for programmers familiar with procedural
programming.  Since one of the main driving forces for
the adoption of object-oriented programming will be
the need to produce programs that run under the new
graphical user interfaces, changing from procedural to
object-oriented programming may involve changing not
just the language being used, but the operating
environment, resulting in an extremely steep learning
curve.

For those lucky (or clever?) enough to be using the
right languages, there is an alternative to the
extreme course of learning a new language and
operating environment at the same time: that is to
begin using a 'hybrid' object oriented language, to
familiarise oneself with the language aspects of
object orientation, perhaps before it becomes
necessary to change to a graphical environment as
well.

C++ is a very good example of such a hybrid language.
In the commercial world, C++ has become the de facto
standard for object oriented languages largely because
of its roots in the C language, which make it
accessible to the enormous body of existing C
programmers.  Hybrid object oriented languages
typically allow a mix of procedural and object
oriented code to coexist in the same program, so that
developers are not forced to rewrite systems, but can
take advantage of object orientation incrementally.

DB-TALK makes Clipper a Hybrid object oriented
language allowing a mix of 3GL procedural code  of the
basic Clipper language, the object orientation of
Class(y).lib, the Graphical User Interface of Gforce
and the 4GL facilities of the ADL Class library.

Class(y) is an add-on library for Clipper which
extends the language by providing the ability to
create and manipulate new classes, thereby making
Clipper the latest entry into the select group of
hybrid object oriented languages.

Gforce is an add-on library for Clipper which gives
Clipper language complete control over VGA graphics.

ADL Class library provides the Clipper language with a
simple GUI in DOS. It also provides 4GL facilities
through abstraction that enable separation of design
and implementation issues of  application development.

DB-TALK has an advantage over Clipper that it is an
interpreter and design objects do not have to be coded
or converted into code but can be created by various
visual design tools and stored as resources with code
providing more flexibility.

This document will give a brief overview of object
orientation, and define most of the important terms,
as a prelude to a tutorial-style introduction of the
use of DB-TALK

@@ History

History of Object-Oriented Languages

The concept of an object class and inheritance,
central to object oriented languages, was first
implemented in the language Simula in the 1960s.
Simula, as its name implies, was intended as a
language for programming simulations, and never really
entered the mainstream.

The major milestone in the development of object
oriented languages was the Smalltalk research project
at Xerox Palo Alto Research Centre (PARC). Starting in
the early 1970s, the Smalltalk project, initiated by
Alan Kay, had as its goals more than just the
development of a programming language; rather, a
complete integrated environment was the goal,
including an object-oriented language, development
tools, and a graphical interface. The standard
components of modern graphical interfaces, such as
windows, icons, and the mouse, were pioneered at Xerox
PARC.

The Smalltalk language itself was the first 'true'
object oriented language in that it dealt exclusively
with objects.  All subsequent object oriented
languages have been based on the concepts used in
Smalltalk.

Smalltalk was important, not just for its language,
but for the development tools available in the
Smalltalk environment.  These include class browsers
and object inspectors.  A class browser is a very
powerful tool which allows program code to be edited
in a much more convenient and structured way than with
conventional editors.  Because of the inherently
well-defined structure of object oriented programs,
the class browser is capable of displaying a given
program's class tree in graphical form, allowing the
user to 'point and shoot' to select a particular
method (procedure) to be edited.  Many programming
tasks become menu driven, such as the creation of new
classes, modifying the structure of the class tree,
and modifying the structure of a class.  These
operations are far more complex if performed in a
traditional editing environment.

Tools such as these are an integral part of the
promise of object oriented technology.  They can
simplify a programmer's life, reducing development
time and costs.  Although they are a rarity in the DOS
world at present, as the move toward object oriented
technology grows, they will become more commonplace.

@@ Object?

What is an Object

One of the fundamental reasons that object orientation
is enjoying such success as a programming paradigm is
very simple: the real world is made up of objects.  An
invoice is an object.  A stock item is an object.  A
balance sheet is an object.  An entire company is an
object.  Objects can contain other objects; and in
this way complete systems can be constructed using
objects.

But what is an object from a programming point of
view?  Simply put, it is a collection, or module,
containing both procedures and data.  This is not very
enlightening in itself; but before we can explain it
better, we need to explore some other concepts.

@@ Class

Classes, Instances and Instance Variables

In any given system, many objects will exist.  Some of
these objects will be very similar: for example, you
might have thousands of invoice objects stored on
disk.  Although each one is different, they all share
a common set of attributes.  The same operations are
valid on all of them.  A 'class' consists of
procedures and data which are common to all the
objects
which are members of that class.  An invoice class
would contain the procedures for printing invoices,
for example.

To summarise, then, we can define the term 'object' in
another way: an object is an 'instance' of a class.  A
given class may have many instances of itself
(objects) in existence at any one time.  Each of these
instances has the same basic structure as its parent
class, but they are distinguished from each other by
the data contained within them, which is stored in
'instance variables'.

These instance variables, like any other variables,
have names. An invoice object might contain instance
variables such as 'date', 'customer', and 'amount'.
These instance variables are not normally accessible
outside of the object; as described below, they are
only accessed via that object's methods.

@@ Methods

Messages and Methods

We defined an object, earlier, as a module containing
both procedures and data.  An object's procedures are
known as 'methods'.  This terminology helps to
distinguish them from procedures which are not
associated with an object, since there are fundamental
differences.  In a fully object oriented system such
as Smalltalk, there are no procedures, only methods.
In a hybrid system such as C++, or DB-TALK, both
methods and procedures can coexist.

Methods are not called in the same way that procedures
are.  Rather, 'messages' are sent to objects, which
respond by executing the appropriate method.  All
valid operations on or using the data in an object are
defined by its methods, so all operations on an object
are accomplished by sending messages to the object.
Because of this, it is not necessary for other objects
to access, or even know about, the internals of
foreign objects. Objects behave like black boxes: send
them a message, and they respond by executing the
appropriate method.  Send the 'print' message to an
invoice object, and it will respond by printing
itself.  This black box approach is known generally as
'encapsulation', and while it is possible to achieve
in procedural systems, object oriented systems
actively encourage, support and enforce it.

@@ Inheritance

Inheritance: Superclasses and Subclasses

Common properties among groups of classes can often be
combined to form a 'parent class', or 'superclass'.
For example, it would make sense for a quotation
class, an order class, and an invoice class all to
share the same superclass, a sales document class.
The quotation, order, and invoice classes are then all
'subclasses' of the sales document class.  This is
known as 'inheritance'.  The subclasses have inherited
all the properties of their superclass, and may add
unique, individual properties of their own.  This
concept can be extended further, with subclasses of
subclasses. Class trees seven or more levels deep are
very common in object oriented systems.

This is one of the most powerful features of object
oriented programming, since it allows reuse of
existing code in new situations without modification.
When a subclass is derived from a superclass, only the
differences in behaviour need to be programmed into
the subclass.  The superclass remains intact and might
continue to be used as is in other applications, where
other subclasses are using it in different ways.

@@ Polymorphism

Polymorphism

This is not a new concept, just a new term.  It refers
to the fact that the same message, such as 'print',
can result in different behaviours when sent to
different objects.  Sending the print message to a
graph object has a very different effect than on a
balance sheet object.  Polymorphism has benefits for
the programmer in that consistent names are used, but
its implications go deeper than that.  It means that a
message can be sent to an object whose class is not
known.  In a procedural system, given a variable of
unknown type, a case statement would typically be
required to test the type of the variable and pass it
to the correct procedure for the desired operation.
In an object oriented system, a message is sent to the
object with no testing, and the object responds
accordingly.

@@Overview

Overview of DBTALK

DB-TALK extends the Clipper language by providing the
ability to create and use user-defined object classes,
allowing fully object-oriented programs to be
written.  It provides all the key features of an
object oriented language, including inheritance, with
the consistent simplicity of Smalltalk, the real-world
practicality of C++, and the database power of
Clipper.

DB-TALK consists of a Resource Compiler, Visual tools
for GUI screens, Database Views, Columnnar Reports,
Graphics Bitmaps, Icons and fonts. Object oriented
Clipper programs can be written and compiled into
codeblocks in conjunction with other resources, then
linked with the ADL Class library to form an EXE file.

DB-TALK makes use of, and extends, Clipper's limited
built-in object oriented capabilities, specifically
the send operator, or colon.  In Clipper, a message is
sent to an object as follows:

    object:message(parameters)

DB-TALK slightly changes this syntax. In DB-TALK, a
message is sent to an object as follows:

    object:Send('message', parameters)

With DB-TALK, it is possible to mix and match
programming styles.  On the one hand, object classes
can be developed and used in normal procedural
programs, in the same way that the built-in TBrowse
and Get classes are used in Clipper.

At the other extreme, complete object oriented systems
can be developed, in which no stand alone procedures
exist, other than a startup procedure 'Main'.  The
startup procedure initialises the system and from then
on, all program execution is effected by passing
messages between objects.

Any desired mix of these two approaches may be used,
allowing developers to gradually familiarise
themselves with the benefits of object-oriented
programming.

The following sections form a tutorial for creating
and using user defined object classes.

@@ Create Class

Creating a Class

Perhaps the most fundamental feature required of an
object oriented programming language is the ability to
create new object classes.  Although standard Clipper
does not provide this capability, DB-TALK provides the
means to do this.  In DB-TALK a class consists of a
class specification, which describes the overall
structure of a class, and the class implementation,
which contains the actual code for the methods of that
class.

To illustrate the creation of a class, we will use as
a rectangle class as a simple example.  Here is the
class specification:

* rectangle.prg

#define TOP    1
#define LEFT   2
#define BOTTOM 3
#define RIGHT  4

CLASS REC

  METHOD width
    LOCAL x:=self:set()
  RETURN x[RIGHT] -  x[LEFT] + 1

  METHOD height
    LOCAL x:=self:set()
  RETURN x[BOTTOM] - x[TOP] + 1

  METHOD area
    LOCAL nArea
    nArea = self:Send('Width') * self:Send('Height')
    self:private(nArea)
  RETURN nArea

  METHOD NewPos
    PARAMETER nTop, nLeft, nBottom, nRight
    nTop =    MAX (1, nTop)
    nLeft =   MAX (1, nLeft)
    nBottom = MIN (maxrow(), nBottom)
    nRight  = MIN (maxcol(), nRight)
    self:Set( {nTop, nLeft, nBottom, nRight} )
  RETURN

END CLASS



DB-TALK classes are identified by a three character
identifier which becomes a prefix on all the names of
methods belonging to the class.

The first statement, CLASS, is straightforward.  We
are creating a class identified by REC. All following
statements up to the END CLASS statement should be
DB-TALK Method definitions of class REC.

DB-TALK does not have instance variables, rather each
object has instance values held in a private and a
public data structure (arrays) which are accessed by
special methods 'private' and 'set' respectfully. How
this works will be more clearer when we use the REC
class we have declared.

Using the Class

Before we cover the actual implementation of the
class, we will look at how the class would be used.

* testrect.prg

PROCEDURE main

    PRIVATE oRect

    oRect := ADLClass('REC', {5,10,15,40})

    qout( 'The dimensions of Rectangle oRect are as
follows:')

    qout( '      width:', oRect:send('width'))
    qout( '     height:', oRect:send('height'))
    qout( '       area:', oRect:private())

RETURN

* eof testrect.prg

This program creates a new instance of the class
Rectangle and assigns it to the local variable
'oRect'.  The statement:

    oRect := ADLClass('REC',aInCoord)

can be understood as sending the 'REC' message to the
ADL Class maker class, which has the effect of
creating an instance of the REC class with the
specified dimensions.

The second parameter to the ADLClass is the object's
public data structure and is used to set the
dimensions of the Rectangle.  What the contents of
this array should be depends on what instance values
are need by the class.

Once we have created our object, we can use it just as
we would any other Clipper object, by sending it
messages.

The statement oRect:Send('width'), for example, sends
the width message to the Rectangle oRect.  In this
particular case, this has the effect of invoking the
width method, which calculates
and returns a result.

Running this program produces the following output:

    C:\>testrect

    The dimensions of Rectangle x are as follows:
          width:         31
          height:        11
          area:         341

Error 0 Private Scope Violation for PRG at line 20 in
PRGmain
Operation :
Called from ABORT Line: 129
Called from obj:PRIVATE Line: 68
Called from (b)STRTOARR Line: 0
Called from obj:SENDIT Line: 383
Called from obj:ADLOBJSEND Line: 210
Called from ADLQE Line: 61

We have an error.  Looking at line 20 of TESTRECT.PRG,
we see that we have tried to print the value of the
rectangle area instance value which was put in the
private data structure.  What is wrong with that?.
Private instance values accessed through the 'Private'
method can only be accessed by methods belonging to
class Rectangle.  Our program, TESTRECT.PRG, is not a
Rectangle method, and so is prevented from accessing
this method.

Private instance values are one of the fundamental
benefits of object oriented programming.  By making an
instance value private, we ensure that only a
relatively small set of routines (the methods of that
class) can change that variable.  If the variable's
value is incorrect, we know exactly which routines to
examine.

It is considered bad object oriented practice to allow
instance values to be changed outside of their class.
However, it is often necessary, and acceptable, to
obtain, but not set, an instance value outside of the
class.  To facilitate this, a method can be defined to
access the value.

Class Implementation

The class implementation consists of code for all the
methods specified for that class.  This code is
usually placed in a different file from the class
specification.

When writing methods, you need to be aware of how a
method differs from a normal function or procedure.  A
method, unlike a normal function or procedure, is not
called directly, but rather is invoked as the result
of a message sent to an object.  A method cannot be
called with no object.  A method acts on the object
receiving the message; but to do so, it needs to be
able to access it.  To this end, the variable 'self'
exists in all methods, and it refers to the object
which received the message that is being acted on.
Instance variables and methods belonging to that
object are accessed via the 'self' variable.  In the
WIDTH method in the code above, for example, the line:

    x = self:Set()

assigns the public instance values of the rectangle
receiving the WIDTH message.

The code of the methods is mostly self-explanatory.  A
new keywords are used: METHOD.

The METHOD keyword is used when declaring a procedure
or function, as can be seen above.  All methods should
be declared in this way.

Now that we have finished with RECTANGLE.PRG, we have
the makings of a complete system and can actually test
it.  The system can be compiled as follows:

    dbtalk rectangle.prg /o
    dbtalk testrect.prg

This should create the file TESTRECT.EXE which can
then be run.  Note that the /o switch is used to
create RECTANGLE.ADL which is declared external in
TESTRECT.

@@ Inheritance

Inheritance

An object oriented language is not complete if it does
not support inheritance.  Inheritance is the mechanism
which allows existing code to be reused in different
circumstances without modification.

As an example, we will declare a class called
ScreenRect which can draw a rectangle on the screen
and manipulate it.  Since we already have a rectangle
class, we can save a lot of time by inheriting from
that class.

The code below defines the class ScreenRect.  A new
feature which has been used here should be explained
in advance, because of it's ubiquity.  The double
colon (::) is a shorthand notation for sending a
message to the self object in a method.  This is
particularly useful in a statement such as the
following:

self:Send('hide')

With the double colon, this becomes:

::Hide

which might look strange at first, but once you are
used to it, is easier to read than the alternative.

Here is the code for the ScreenRect class:

*  scrnrect.prg

CLASS SRT

INHERIT RECTANGLE

    METHOD hide
      LOCAL aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      restscreen(nTop, nLeft, nBottom, nRight,
self:Private())
    RETURN

    METHOD show
      LOCAL cScreenBuf, aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      LOCAL cColor:=aScrnRect[5],
nBoxStyle:=aScrnRect[6]
      cScreenBuf := savescreen(nTop, nLeft, nBottom,
nRight)
      dispbox(nTop, nLeft, nBottom, nRight, nBoxStyle,
cColor)
      self:Private(cScreenBuf)
    RETURN

    METHOD MoveUp
      PARAMETER n
      LOCAL aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      ::hide
      ::NewPos(nTop - n, nLeft, nBottom - n, nRight)
      ::show
    RETURN

    METHOD MoveDown
      PARAMETER n
      LOCAL aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      ::hide
      ::NewPos(nTop + n, nLeft, nBottom + n, nRight)
      ::show
    RETURN

    METHOD MoveLeft
      PARAMETER n
      LOCAL aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      ::hide
      ::NewPos(nTop, nLeft - n, nBottom, nRight - n)
      ::show
    RETURN

    METHOD MoveRight
      PARAMETER n
      LOCAL aScrnRect:=self:Set()
      LOCAL nTop:=aScrnRect[1], nLeft:=aScrnRect[2]
      LOCAL nBottom:=aScrnRect[3],
nRight:=aScrnRect[4]
      ::hide
      ::NewPos(nTop, nLeft + n, nBottom, nRight + n)
      ::show
    RETURN

* eof scrnrect.prg

A number of new techniques have been used in this
example above.  First and most important is
inheritance.  The ScreenRect class has been declared
by inheriting from the Rectangle class, using the
statement:

    INHERIT Rectangle

This means that the ScreenRect class inherits all of
the instance values and methods of the Rectangle
class, in addition to its own instance values and
methods.  In the 'hide' method, for example, the
instance values for nTop, nLeft, nBottom, and nRight,
which are Rectangle instance value, have been
accessed, along with 'screenBuf', which is a
ScreenRect instance value.

Inheriting from another class raises an issue with
regard to the
data structure of the parent class, or 'superclass',
should strictly speaking also be initialised when the
object is created.  As the superclass should have its
own data structure, it makes sense to intialise it.
DB-TALK automates this process, by allowing the
combined data structure to be intialised when the
objects are created. In the example below, the line:

    LOCAL rect1 := ADLClass('SRT', {5, 5, 10, 25,
'R+/BG', 1} )

declares a screen rectangle object with a data
structure of 6 instance values. The first four belong
to the RECTANGLE class while the last 2 are for the
SCREENRECT class. The data structure passed as a
parameter should of course, correspond with the data
structure expected by the superclass methods in this
case that of the class Rectangle.

Below is a sample program to use the SCREENRECT class.

* testscrn.prg

EXTERNAL scrnrect

FUNCTION main
    LOCAL i:=1
    LOCAL rect1 := ADLClass('SRT', {5, 5, 10, 25,
'R+/BG', 1} )
    LOCAL rect2 := ADLClass('SRT', {15, 60, 22, 75,
'R+/BG', 2})

    DO WHILE ! i > 10
       rect1:Send('MoveDown', 1)
       rect1:Send('MoveRight', 1)
       rect2:Send('MoveUp', 1)
       rect2:Send('MoveLeft', 1)
       i = i + 1
    ENDDO

RETURN

* eof testscrn.prg

This sample program will allow us to test the
ScreenRect class.  Compile as follows:

    dbtalk rectangl.prg /o
    dbtalk scrnrect.prg /o
    dbtalk testscrn.prg

Note that the RECTANGLE program is compiled as object
files to be linked in SCRNRECT.  If it is not
pre-compiled, a compilation error will occur regarding
an external symbol RECTANGLE. The same thing applies
to SCRNRECT with TESTSCRN.

You can now run TESTSCRN.EXE.

@@ADL Class Lib

ADL Class Library

It is now apparent that to make the shift to OOP
(Object-oriented programming) requires a significant
up-front investment of effort to create a foundation
of reusable code upon which to build applications.
Essential for maximum productivity, this foundation
must be comprised of a least the classes of objects
needed for everyday programming, such as classes for
the user-interface, the database and report writing.
Adding a GUI (Graphical user Interface) and event
driven programming on top, this becomes a most
daunting task.

DB-TALK makes this an easy task by providing you with
a basic class library to handle the GUI, the database
and reports leaving you free to concentrate on
creating application classes which deal with the
functional issues of your application. DB-TALK also
provides visual tools that simplify greatly the task
of specifying the objects for each class supported.

DB-TALK is supplied with 9 pre-defined classes.
DB-TALK pre-defined classes are of two types.

The first type are known as the Built-in classes. The
methods for these classes are compiled and are part of
the DB-TALK run-time which is automatically linked
into all compiled programs.

The second type are known as the External classes. The
methods for these classes are compiled into object
files and have to be included manually into each
application that requires them.

The decision to make a class built-in or external was
dependent on a balance between speed and size.

Builtin Classes

There are two types of built-in classes. Those that
are system declared and those that are user-declared.
Generally, DB-TALK creates objects of the system
declared classes, while the user creates objects of
the user-declared classes. In some cases, developers
may need to reference system objects created on their
behalf.

For example, the 'PRG' class is system declared. It is
the default class. All DB-TALK functions and
procedures without a CLASS identifier (non methods)
are compiled into methods of this class. When a
compiled DB-TALK application starts, a 'PRG' object is
created. DB-TALK then passes this object the message
'Main'. What happens after that depends on what the
developer has coded into 'Main'.

Even though the developer has not created this 'PRG'
object, in order to call another function or procedure
within the same class (application), this object has
to be referenced through the self identifier.

User-defined classes are explicitly declared by the
developer. Objects of these classes should be treated
like normal variables. The scope and life of these
objects should always be considered.

@@ SCN Class

SCN Class (User defined)

The Screen Class allows the design of screens, a
DB-TALK version of GUI forms/dialog boxes. GUI forms
are attractive windows designed for entering and
displaying data. They employ a number of
user-interface controls, such as text boxes, push
buttons, radio buttons, and listboxes to handle
interaction with the user.

DB-TALK also provides a screen editor which simplifies
the task of specifying these controls. For example :

SCREEN laserscr
....
.....
oLaserScn = ADLClass ('SCN', laserscr)

The first statement causes the DB-TALK resource
compiler to include as a resource in the current
compilation the screen design found in file
'laserscr.scn'. This specification is the data
structure of an SCN class object.

The second statement executed at run-time causes an a
SCN object oLaserScn to be created. This object will
respond to normal SCN messages 'Display', 'Read',
'Clear' etc.

@@ FLD Class

FLD Class (System defined)

Even though the developer declares the whole screen
including its controls as a SCN object, DB-TALK
generates internally, a FLD object for each control.
The developer does not need to know of their
existence. However when the need arises to do
something to a user control in isolation of the
others, its object can be requested for an used. For
example, using our SCN object above :

oLaserScn = ADLClass ('SCN', laserscr)
oDesc = oLaserScn:Send('Object', 'DESC')
oDesc:Send('Refresh')

the SCN object oLaserScn is told to return the FLD
object of a textbox called 'DESC'. The oDesc FLD
object will respond to normal FLD messages 'Refresh',
'Edit', etc.

@@ PRG Class

PRG Class (System defined)

As mentioned earlier, the PRG class is used by DB-TALK
and only one instance of exists throughout the
application. Its purpose is to interpret all free
standing functions and procedures that do not belong
to any user-defined class. It is through this class,
that a developer can mix procedural and
object-oriented programming.

To code DB-TALK programs procedurally, a developer can
display a screen and use a read loop to accept all
events on the screen until an exit event is received.
Within the loop, a CASE structure can be used to
handle the expected messages in a structured way.

On the other hand, an event-driven approach can be
adopted. Like the procedural approach, a developer can
display a screen and use a read loop to accept all
events on the screen until an exit event is received.
However, this is where the similarity ends. Instead of
using a CASE structure, a hierarchy of event handlers
are used to handle the expected events. The handler at
the top of the hierarchy is the system handler which
receives all events. If the event is not handled at
system level it is passed to the screen handler. If
the screen handler does not reecognise it, then it is
finally passed to the application which has to deal
with it.

The difference between the two is that the procedural
approach is fixed in how a user can use the
application, while the event-driven approach will
allow the user flexibility in use.

@@ DBF Class

DBF Class (User defined)

A database is a collection of related tables. DBF
files are in fact tables. DB-TALK provides a DBF class
to define database views. A database view is a subset
of a complete database. It hold a subset of the
tables, relationship rules about the tables and only
the fields of each table needed to support a complete
interaction of the user with a Screen.

DB-TALK supplies a Database View editor which can be
used to create and modify DBF files, Index files and
DBF relationships. It can also be used to populate the
DBF files with data manually or from a wide variety of
sources.

To use the DBF class is as straight foreword as
writing normal Clipper DML (data manipulation
language). For example :

DATABASE  invoice
...
...
oLaserDbf = ADLClass ('DBF', invoice)
oLaserDbf:Send('Open')
oLaserDbf:Send('Read', 'INVOICE')

This translates into normal xBase as:

SELECT 0
USE CUSTOMER
SET INDEX to CUSTOMER

SELECT 0
USE INVOICE
SET INDEX to INVOICE
SET RELATION TO cust_code INTO CUSTOMER

SELECT 0
USE INVOICELIN
SET INDEX TO INVOICELIN
SET RELATION to inv_no INTO INVOICE

m->inv_no   = invoice->inv_no
m->inv_desc = invoice->inv_desc
......
......

@@ REP Class

REP Class (User defined)

DB-TALK columnar reports are simply standard dBASE III
reports.  DB-TALK through OOPS gives more flexibity in
programming reports. There are simply three methods to
use. The first one called at the beginning of the
report initialises the report and prints the headings.
The second one is called to print each detail line and
group totals generated. The last one terminates the
report printing the final totals.

DB-TALK provides a report designer tool that enables a
developer to set-up the  report layout. DB-TALK
provides flexibility in the printing as the developer
should provide a device object which will respond to
three messages issued by the report writer.

This is a classic example of polymorphism as the
report writer does not know which device it is
printing to. It could be a printer, disk file Word
processor file or even a fax.
Any device object could be used provided it responds
to the messages it receives. For example :

    REPORT laserrep
    .....
    .....
    oLaserRep:=   ADLClass('REP', laserrep)
    oLaserWp:=    ADLClass('WP', {'WP', 'laser.doc',
''} )
    oLaserTxt:=   ADLClass('TXT', 'laser.doc')

   IF YESNOBOX('Selection',' WordPerfect or DOS text')
      oLaserPrn = oLaserWp
   ELSE
      oLaserPrn = oLaserTxt
   ENDIF

    oLaserPrn:Send('Open')
    oLaserRep:Send('Initiate', oLaserPrn, '')
    oDbView:Send('Gotop','LASER')

   DO WHILE ! oDbView:Send('eof', 'LASER')

       oLaserRep:Send('Generate')
       oDbView:Send('skip','LASER',1)
   ENDDO

    oLaserRep:Send('Terminate')
    oLaserPrn:Send('Close')
    oDbView:Send('Gotop','LASER')

@@ WP Class

WP  Class (User defined)

DB-TALK has no built-in print drivers. Instead it uses
word processor documents as its printing protocol.
DB-Talk supports Word Perfect,  Lotus Manuscript and
Lotus 1-2-3 formats. It uses this WP class to hides
all complications and codes needed to create a WP
document. Once a document object is created, data is
sent to the object via different messages. The object
deals with all internal rules of the different formats
and maintains a truly Word Perfect, 1-2-3 or
Manuscript compatible file.
On a network, this enables Word Perfect, 1-2-3 or
Manuscript to be used as a print server for DB-TALK
applications.

With Manuscript objects, a new document can be made
from an existing template. Also, various markers can
be inserted included PIC files generated from the
CHART class. For example :

oLaserWp:= ADLClass('WP', {'MS', 'laser.doc',
'laser.set'} )
oLaserWp:Send('Open')
oLaserWp:Send('Addline', 'Below is a chart of
categories')
oLaserWp:Send('Addpic', 'chart2d.pic')

This causes the Manuscript document 'laser.doc' to be
created from the template document 'laser.set'. It
will inherit all global format settings in
'laser.set'. The first line will be the text 'Below is
a chart of categories' and after that will be a marker
for PIC file chart2d.pic which will be seen when the
document is either printed or previewed.

@@ CHT Class

CHT Class (External Class)

The Chart class extends the SCN class by allowing a
SCN button control to be used as a chart. Through the
messages provided, data can be put into the chart and
plotted in three basic styles. The methods
automatically label the chart's axes and scale the
data according to the size of the SCN button control.
If the data changes then the chart is re-scaled and
axis adjusted to reflect the addition of new data. For
comparisons, more that one set of data can be plotted.

Optionally, if a hard copy is required, a PIC file can
be generated from a chart and using the WP class
(Manuscript only) be inserted into a document. For
example:

    SCREEN  lasercht
    ......
    PRIVATE aChartXaxis, aChartVals, aChartValBlk:={||
aChartVals}
    .......
    aChartXaxis =
{'ACT','MYS','SUS','CHI','COM','DOC','DRA','FOR','NOR',
'MUS','MSC','SCF'}
    oLaserChart:= ADLClass('SCN', lasercht)
    aChart = oLaserChart:Send('Attributes', 10)
    oChart = ADLClass('CHT', {aChart, aChartValBlk,
aChartXaxis, 'Distribution of Film Categories'} )
    oChart:Send('LineGraph')

The code above can be used to display a linegraph in
screen lasercht using the screen button control
associated with event value 10. The array aChartvals
contains each set of values to be plotted, the X axis
will be labelled by aChartXaxis array.

@@ TXT Class

TXT Class (External Class)

The DOS text file Class is a simple means of using a
DOS text file as a device driver instead of the
built-in WP class. The methods are shown below :

CLASS TXT

FUNCTION Open
   PRIVATE txtfile, handle
   txtfile = self:set()
   handle = FCREATE (txtfile)
   self:Private(handle)
   RETURN

FUNCTION Add
   PARAMETER txt
   FWRITE (self:private(), txt)
   RETURN NIL

FUNCTION Addline
   PARAMETER txt
   FWRITE (self:private(), txt+chr(13)+chr(10))
   RETURN NIL

FUNCTION Close
   FCLOSE (self:private())
   RETURN NIL

FUNCTION NewPage
   FWRITE (self:private(), chr(12))
   RETURN NIL

Notice the use of the private data structure to hold
the file handle. This will protect it from any program
that uses this class. To declare an DOS text file
object requires :

    oLaserTxt:=   ADLClass('TXT', 'laser.doc')

@@ PRN Class

PRN Class (External Class)

To complete the Printing device Classes, a direct
printer Class is provided. The code is self
explanatory.

CLASS PRN

FUNCTION Open
   SET (23, .T.)   // Clipper Set printer ON
   RETURN

FUNCTION Add
   PARAMETER txt
   QOUT (txt)
   RETURN NIL

FUNCTION Addline
   PARAMETER txt
   QOUT (txt+chr(13)+chr(10))
   RETURN NIL

FUNCTION Close
   SET (23, .F.)   // Clipper Set printer OFF
   RETURN NIL

FUNCTION NewPage
   QOUT(chr(12))
   RETURN NIL

@@Language

DB-TALK Language

To do anything useful with DB-TALK involves coding a
Function or Procedure. DB-TALK does not make any
difference between the two. In fact both names are
interchangable.

Execution starts with a Function named 'Main'.

There are no commands in a DB-TALK Function. A DB-TALK
Function starts with the  function declaration
'FUNCTION' and ends with 'RETURN' which can prefix an
optional expression to be evaluated and passed back as
the value of the Function.

The body of the Function consists of variable
declarations, control constructs and expressions to be
evaluated. The evaluation always results in a value
and this value may be ignored, assigned to a variable
which will inherit its data type from the value or can
be used by a control construct to make a decision.

DB-TALK functions can contain comments which must have
an asterisk in column one or // after the expression.
In addition DB-TALK supports a special comment which
can be used for debugging.

Any comment line which begins with a double asterisk
will be interpreted as a normal DB-TALK expression if
'TRACE' has been set on with the SETTRACE function.
This will allow status describing comments to come
alive when a trace is required to find out what a
DB-TALK function is doing.

For example :

FUNCTION DisplayFile
PARAMETER cFileName

** 'File is '+cFileName
*  Test if file exists

IF file (cFileName)
   fp = FOPEN(cFileName)   // Open File
...

If TRACE is on, then whenever this function is
invoked, it will report into the log file, the name of
the file it is about to display.

@@ Expressions

DB-TALK Expressions

A DB-TALK expression is a stack of objects operated
upon by their methods. Expressions are normally
written in shorthand mathematical form.

For example, consider the numeric expression a + b /
(c - d) can be written as DIVIDE ( ADD (a, b),
SUBTRACT (c, d) ) if we assume Clipper Operators '+',
'/' and '-' are the shorthand form of the Clipper
Operator Class Methods Add, Divide, and Minus.

Expressions consist of basic Clipper Operators,
Clipper Functions, DB-TALK pre-defined Class Methods,
user-defined Class Methods and DB-TALK Functions.

@@ Operators

There are four Operator Classes:

Arithmetic, Relational, Logical and String and Date

Arithmetic Operators

The following arithmetic operators are supported by
DB-TALK

+    Addition
-    Subtraction
*    Multiplication
/    Division
%    Modulus (returns the remainder or a division)
^    Exponential
**   Exponential

Operations are solved from left to right. First, any
portions of the expression in parentheses is
performed. Second, exponentiation is performed. Third,
multiplication and division are performed. Last,
addition and subtraction are performed.

Relational Operators

The following relational operators are supported by
DB-TALK

<    Less than

>    Greater than

=    Equal to

==   Exactly equal to

#    Not equal to

!=   Not equal to

<=   Less than or equal to

>=   Greater than or equal to

$    is contained in

The result of all relational operations ie either TRUE
(.T.) Or FALSE (.F.). Evaluation can be evaluated from
left to right and parentheses can be used to alter the
order of evaluation as they all have the same
precedence. Relational operators have lower precedence
than arithmetic operators.

Logical Operators

The following logical operators are supported by
DB-TALK

.AND. Both the left and right expressions must be
       true for the whole expression to be true

.OR.  If either the left and right expressions is
       true, the whole expression is true

.NOT.  Negate expression

Logical expressions are evaluated in the following
order:

1.   Any expressions in parentheses

2.   .NOT.

3.   .AND.

4.   .OR.

String Operators

There are two string operators are supported by
DB-TALK

+    Concatenation with trailing spaces
-    Concatenation without trailing spaces

Date Operators

There are two date operators are supported by DB-TALK

+    Add days to a date to derive a new date
-    Subtract days from a date to derive a new date or
subtract two dates.

Object Operators

There are two object operators in DB-TALK

Send  Passes a message to a DB-TALK object and causes
       a method to be invoked
Set   It is used to get and/or set the data structure
       of a DB-TALK object.

@@ Variables

DB-TALK Variables

DB-TALK supports eight types of memory variables :

1.   String (Max 64K)

2.   Numeric (Max 19 bytes)

3.   Date (8 bytes)

4.   Logical (1 byte)

5.   Bit Map (8 bits per byte Max 64K)

    3 functions are provided to manipulate bit
     strings

     lOn = BitTest(cBitString, nPosition)

     cNewString = BitSet(cBitString, nPostion)

     cNewString = BitReset(cBitString, nPosition)

6.   Clipper Code Blocks

7.   Clipper Objects

8.   DB-TALK Objects

DB-TALK supports arrays. Arrays can consist of 4096
elements. Elements are independent in type and each
element type can be of the six types including nested
arrays. They follow the same rules as memory
variables.

Careful selection of a variable's scope is important
to a function's readability. When you declare a
variable the trick is to restrict it to only where it
should be seen. It should be invisible everywhere else
otherwise you will have problems tracking it. If you
are not into the habit of declaring your variables
where you need them you wont be able to appreciate the
complexity of writing the code of DB-TALK.

When you are studying a function from a 10,000 line
program, the fewer things you have to worry about the
better.

The lifetime of a variable of determines how long the
variable hangs around in memory. This differs from its
scope. A variable may go out of scope so you cannot
access it any longer, but its value may remain so that
it is available the next time it comes into scope.
Again the shorter the lifetime, the better. There is
nothing more frustrating than to trying to work out
what an used variable is doing.

DB-TALK supports one basic scope for variables;
Private. Global and Local scopes can be simulated.

If a variable has a private scope, it is visible in a
particular function and any called from it. You
declare variables with a private scope using the
'PRIVATE ' key-word, followed by a comma separated
list of variable names. For example

FUNCTION main_process      FUNCTION sub_process
PRIVATE a                  .....
a = 15                     QOUT (a)
SUB_PROCESS ()             RETURN
RETURN

The variable a is visible inside sub_process but will
not be visible from a function that calls
main_process. This is private scoping. IF a is
declared within sub_process, the value of a in
main_process will no more be visible in sub_process.
DB-TALK will create a new copy of it and the QOUT
function will result in a run-time error as a does not
have a value. This is simulated local scoping.

A variable with global scope is visible everywhere
from the moment it is declared. In DB-TALK, Private
variables declared in 'MAIN' function have a global
scope. Global variables never go out of scope. The
program will have to release global variables
explicitly.

Private and local variables have lifetimes limited to
the duration of the functions in which they are
declared while global variables wait around until the
programmer gets rid of them or till the end of the
program.

@@ Sequences

Sequences

Sequences are a group of DB-TALK expressions evaluated
one after the other. The group of expressions are
delimited with BEGIN and END statements.

Sequences are coded in DB-TALK as follows

BEGIN
   expression 1 ......
   expression 2 ......
   expression 3 ......
END

@@ Selections

Selections

Selections are sequences of expressions to be
evaluated based on the evaluation of mutually
exclusive conditions. Provision is made to evaluate a
'default' sequence if all the conditions evaluate as
FALSE.

Selections are coded in DB-TALK as follows

IF <condition 1>
   sequence 1 ......

ELSEIF <condition 2>
   sequence 2 ......

ELSE
   sequence n ......
ENDIF

<condition 1> is the first trigger. If <condition 1>
evaluates as TRUE, then sequence 1 is evaluated
otherwise <condition 2> becomes the next trigger. IF
both or more conditions all evaluate as FALSE, then
sequence n will be evaluated by default. 'ELSEIF' and
'ELSE' are optional in the construct.

@@ Iterations

Iterations

Iterations are sequences of expressions that a are
evaluated over and over until an exit condition
becomes TRUE.

Iterations are coded in DB-TALK as follows

sequence 1

DO WHILE <condition>
   sequence 2
   [EXIT]
   sequence 3
   [LOOP]
   sequence 4
ENDDO

sequence 5

<condition> is the main controller of the loop. If
<condition> evaluates as TRUE after the last
expression in sequence 1, then the iteration will
begin and continue until the last expression in
sequence 4 causes <condition> to evaluate FALSE and
cause control to pass to the first expression in
sequence 5.

EXIT and LOOP are optional and are usually used within
an IF construct to alter the flow based on secondary
conditions. The have the following effects. EXIT
causes the iteration to end and control passes
immediately to the first expression in sequence 5.
Sequences 3 and sequence 4 will be skipped. LOOP
passes control to the beginning of the iteration which
will be the first expression in sequence 2. Sequence 4
will be skipped.

@@ PARAMETER

PARAMETER

This directive declares the parameters to be passed to
a function by listing their names following
'PARAMETER'. When the function is called, it needs to
be passed a list of values or variables. The procedure
refers to these using the declared names. The scope
and life of a parameter is private.

@@ PRIVATE

PRIVATE/LOCAL

Both names are interchangeable. Both declare private
variables whose scope and life is private to the
function in which they are defined.

@@ EXTERNAL

EXTERNAL

This declares an object file which contains a
collection functions and other resources. When
EXTERNAL is specified within a function, it is
actioned by the runtime engine. The '.ADL' file must
be available at runtime. It causes all the collected
resources to have a private  scope and life. When the
function terminates, memory occupied by the resources
is automatically freed. The choice between runtime
EXTERNAL and Compile-time EXTERNAL will depend on
finding a balance between speed and size.

@@ FUNCTION

FUNCTION/END FUNC

These statements delimits a function declaration. A
DB-TALK function is a Clipper array of codeblocks. It
is just another Clipper variable. It has global scope
and global life. The resource compiler puts it into
the auto-load list for the run-time system. When a
compiled DB-TALK program starts, the run-time engine
transfers everything in the auto-load list into
Clipper VM (Virtual memory).

@@ #DEFINE

#DEFINE

To enable readability, especially with object data
structures, named constants can be used. It allows
constants to be used in a program without involving
the run-time engine, thereby reducing memory overhead.
When the resource compiler sees a symbol, it replaces
it with the constant value. For example, given the
following code :

#define K_ESC 27

DO CASE
   CASE nKey = K_ESC

The compiler produces in the codeblocks :



DO CASE
   CASE nKey = 27

Note that #define is case sensitive. The convention
(derived from C) is to define all pre-processor
symbols in uppercase.

@@ EXTERNAL

EXTERNAL

The compile-time version of EXTERNAL causes the
resource compiler to include all the functions and
other resources of an object file in the program being
compiled. It allows class methods to specified
separately from the programs that will use them and
allow re-usability. Each function and resource has
global scope and life.

@@ INHERIT

INHERIT

Has the same effect as the EXTERNAL directive, with
the exception that all methods included now belong to
the class associated with the file being compiled.

@@ RESOURCE

Normal xBase programs including Clipper use DBF files
as program resources, DB-TALK programs have many more
resources at their disposal, because of the graphic
user interface. When you move the mouse around, a
pointer on the screen moves. This might have an arrow
shape, an hourglass shape, or something completely
different. These pointers are all resources. They are
special bitmaps that any application can use.
Likewise, the icons that appear in dialog boxes. Not
only does DB-TALK use resources for bitmaps, cursors
and icons, but uses them for creating various
application controls. For example, a DB-TALK screen is
maintained as a resource. This makes the specification
of the screen as an object through the 'SCN' class
very simple. It reduces the amount of code required to
define each control specified in the screen.

DB-TALK uses special directives and files for adding
resources to a program. These files are produced by a
variety of visual tools and are compiled by the
resource compiler which attaches the resources to the
application's executable. Because resources are
separate from the code, the appearance of an
application can be changed without having to change
the application's code.

At the start of a program, DB-TALK run-time creates
pointer variables for all resources. When a resource
is needed, DB-TALK goes to the resource section of the
executable and uses the pointer to load the resource
into Clipper VM. The only exception is program code
which is loaded into Clipper VM directly. Any
user-defined resources which are controlled by the
developer must  be loaded into Clipper VMM with the
GETPOINTER function.

The only feature available in DB-TALK and not in
Clipper, is that object specifications can be done
with an external visual tool and used without
compiling into Clipper code. All non-code resources
can be included with the code in the object
specification. Just like code, a developer can inherit
the resources and reuse without knowing the details of
what they are. For example :

It is possible to compile a calculator class
consisting of all the methods, screen, icons, and
fonts required into an object file called 'CALC.ADL'.

To use this calculator in another application, the
developer does not need to know what resources the
calculator uses, simply declare it external and it
becomes operational as in :

EXTERNAL calc

oCalc = ADLClass ('CAL')
oCalc:Send('Initialise')
......
......

DB-TALK supports nine resource types. Each resource
will be explained in detail in the next chapter. The
Visual tool required to maintain it will also be
explained.

@@ SCREEN

SCREEN Resource

DB-Talk screens is composed of a number of controls,
such as textboxes, browse objects etc. When the user
selects a control either by the keyboard or by a
mouse, the control receives a message that it has been
activated. Further action depends on what type of
control was selected.

Action Buttons

Buttons invoke an action. They are used to present
actions (verb items) to the user. For example,buttons
are used to start or cancel operations. DB-TALK
through GFORCE provides four types of buttons :

Momentary buttons :

These buttons simulate a depress when clicked. They
are pressed just like push buttons on a telephone.

Alternate buttons

These buttons require a press to activate and a press
to deactivate like the power switch of a TV.

Indicator buttons

These are buttons that do not move when pressed so
that your application can draw on their surface.

Invisible buttons

This is a special case of a momentary button that can
be pressed but does not visually respond, a bit like a
magic eye.

Radio Buttons and Checkboxes

Radio buttons and checkboxes are used to select from
among a set of choices. They present the user with a
list of choices from which more than one item can be
selected at the same time. When a checkbox is
selected, an X appears inside it. When a radio button
is selected, it is filled with a dark circle. DB-TALK
programs are not notified of these changes.

DB-TALK uses the bit data type to manages radio
buttons and check boxes. Each radio button or checkbox
corresponds to a bit position in a bit string. DB-TALK
will automatically set and reset the appropriate bits
when the user sets or resets the associated radio
button or checkbox.

 Use radio buttons and checkboxes to present choices.

Data Entry Fields

Data entry fields are used for entering data. Data
entry fields are used to support three types of data
entry.

Clipper GET objects (Only Available in advanced
Runtime Engine)

These are standard xBase @ .. get data entry fields.
In DB-TALK programs, they are used to enter a single
line of data. The data could be of type numeric, text,
date or logical. The developer has control on the
picture, colour and position of each Get object.

Clipper Memo fields

These are multiple text line fields. DB-TALK uses the
standard Clipper memo functions to provide simple WP
like editing on text. The user can move the cursor
through the text in the box, delete characters,
word-wrap and so on.

Clipper TBrowse Objects (Only Available in advanced
Runtime Engine)

A data entry field could also be used for a Clipper
Tbrowse object. Whenever the field is selected,
DB-TALK will activate user-interaction with the
TBrowse object. The Tbrowse object is fully
mouse-aware. The Tbrowse will react to any buttons set
up the screen for cursor control.

Graphic Objects

Graphic objects are static objects. The user cannot
change or modify them, clicking on them has no effect.
They are facilities for display presentation. Their
intended use is to aid the production of professional
looking screens. Basically the add a lot of spice to
the The appearance of the screen.  Text objects can be
use to label the data entry fields. To make graphic
objects active, the developer could put an invisible
button underneath.

Frames

Frames are graphic objects that provide a three
dimensional illusion of height or depth.

Line, Rectangle and Circle

These are basic vector graphic lines, rectangles and
circles drawn between a number of points.

Bitmaps and Icons

Bitmaps are graphical pictures. Placing bitmaps in
screens can add a lot of pizazz. Icons are fixed sized
bitmaps (32x32 pixels) which can illustrations or
logos to screens. Bitmaps can be used like buttons by
placing invisible or indicator buttons underneath.
This causes an event to be activated when the bitmap
or icon is clicked.

Text

Text can be used as captions to label parts of a
screen. For example, they are often used to label text
entry fields.

Creating and using screens

The SCRNEDIT tool is provided to create screens. You
design screens by drawing them. You select controls to
add, then interactively move them on the screen to the
desired position. You can change the size, position,
and other attributes of each control at any time. The
screen tool stores the description of the controls
defined in a SCN file. Icons and bitmaps referenced
are not stored in this file only the reference is kept
in this file. To include icons and bitmaps of a screen
in an application, they must be treated as separate
resources.

To use a screen in an application, the SCREEN compiler
directive is used to cause the resource compiler to
include the screen file in the compilation.

At the beginning of the application, create a screen
object from the 'SCN' class using the ADL Class
library function 'ADLClass'. For example :

SCREEN laserscr
....
.....
oLaserScn = ADLClass ('SCN', laserscr)

Standard Screens

Certain parts of a program's user interface are common
to many applications. In particular, all programs need
a way to display warning messages, obtain simple input
without designing custom screens. DB-TALK provides
pre-defined screen resources called dialog boxes for
this purpose. Each dialog box is accessed via simple
function calls.

@@  MessageBox

MessageBox

Purpose

This is a simple way of displaying messages on the
screen. A heading can be displayed. In addition, up to
five lines of text can be displayed. To spice the
display, an icon resource can be specified to appear
in the top left corner.

Syntax

MessageBox (cHeading, cText, cIconbuff)

Comments

cHeading is a 30 character heading text. cText is a
the message that can be formatted into 5 lines of 30
characters and cIconbuff is an icon resource.

Example

     ICON stop
     ......
     MessageBox ('Warning', 'Backup Files', stop)

@@  TextBox

TextBox

Purpose

This is a simple way of entering a single text
value.  A caption can be displayed.

Syntax

TextBox (cCaption, @cTextVar)

Comments

cCaption is a 30 character text label. cTextVar is the
variable into which the text will be input.

Example

     nAge = 35
     TextBox ('Enter Age', @nAge)

@@  YesNoBox

YesNoBox

Purpose

This is a simple way of enabling the user to make a
Yes or No choice. A heading and a message can be
displayed.

Syntax

lChoice = YesNoBox (cHeading, cText, [cYesOption],
[cNoOption])

Comments

cHeading is a 30 character heading text. cText is a 30
character message. cYesOption and cNoOption are
optional words that can be used instead of 'Yes' and
'No' respectfully. lChoice is logical value indicating
if 'Yes' was chosen or not.

Example

     YesNoBox ('Warning', 'You wish to Quit')

@@  PickBox

PickBox

Purpose

This is a simple way of enabling the user to visually
select an entry from an array. For example, it can be
used to select a file from a directory listing.

Syntax

PickBox (cHeading, aPickArray)

Comments

cHeading is a 30 character heading text. aPickArray is
an array which will contain the entries to be picked
from.

Example

     cFileName = PickBox ('Select File', ADIR('*.*'))

@@  BrowseBox

BrowseBox

Purpose

This is a simple way of enabling the user to visually
select a database record.

Syntax

BrowseBox (cHeading, cFieldName)

Comments

cHeading is a 30 character heading text. cFieldName is
the key field from the correctly opened database file
which will be used to select the record.

Example

     BrowseBox ('Select Employee', 'Emp_No')

@@ DATABASE

DATABASE Resource

The database is the main resource provided by xBase
systems including Clipper. DB-TALK simplifies that
amount of code needed to use this resource. DB-TALK
manages the database files, indexes, filters and
relationships through a Database View resource.

Database Files (DBF)

DB-TALK uses standard Clipper DBF files. The DBF file
contains data about a number of data fields. The
database view allows a subset of the data fields
defined to be selected. The DBF format can natively
deal with the following field types:

Character

Fixed length strings up to 64K.

Numeric

Up to 19 digits in length, counting decimal points in
noninteger fields.

Date

Fixed length of 8 bytes

Logical

Boolean values (.T., .F.) One byte in length

Memo

Variable length character strings (minimum 512 bytes)
stored in companion .DBT file.

Index Files (NTX)

DB-TALK uses Clipper NTX index files. Indexes are
provided to perform fast lookup of records in the DBF
file. They also enable DBF records to be processed in
an order other than numerically.   DB-TALK maintains
the relationships between a DBF and its indexes
through the View resource.

Filters

In most cases, subsets and not the entire data of a
database file is required in an application. When this
situation occurs, records must be filtered. DB-TALK
allows a filter control to be attached to each
database file in a View.

Relationships

Relationships are defined between database files. The
only relationships supported are those classified as
one to many. In other words, many records of one
database file refers to one record in the other. An
example is the relationship between invoices and their
details. Each invoice has many details, but each
detail refers to one invoice. In this example, invoice
is called the parent while the detail is called the
child.

Every time the parent's record pointer is moved, the
child's record pointer is moved to the associated
record.

Creating and using a database

The DBU tool is provided to create a database view.
All the database files, fields, indexes, filters and
relationships can be defined with DBU.  The screen
tool stores the description of the view defined in a
VEW file.

To use a database view in an application, the DATABASE
compiler directive is used to cause the resource
compiler to include the database view file in the
compilation.

At the beginning of the application, create a database
view object from the 'DBF' class using the ADL Class
library function 'ADLClass'. For example :

DATABASE laservew
....
.....
oLaserView = ADLClass ('DBF', laservew)

@@ WALLPAPER

WALLPAPER Resource

The wallpaper resource is used to support the screen resource. It defines an
icon that will be used to paint the screen while the application is loading. It
will remain on the screen during the application unless the screen is cleared
under program control. The wallpaper resource is used to put the icon bitmap
into an application or reusable object file.

For Example :

WALLPAPER zigzag

will include the file 'ZIGZAG.ICN' in the compilation.

@@ PALETTE

PALETTE Resource

The palette resource is used to support the screen resource. It defines a VGA
palette scheme to be used for the application. Although no palette editor is
supplied, a number of palettes are supplied with DBTALK.

The palette resource is used to put the palette file into an application or
reusable object file.

For Example :

PALETTE snowlite

will include the file 'SNOWLITE.PAL' in the compilation.

@@ TEXT

TEXT Resource

The TEXT resource is a simple means of including formatted text into an
application. This can be used for various purposes.

Formatted error messages can included in an application and displayed in a
screen or a report.

It can also be used for printing designer forms.

To access the stored text in an application, the GetPointer function is used as
follows :

    cText = GetPointer (aTextResName)

For example :

TEXT aboutmsg
..
cMess = GetPointer (aboutmsg)

The stored text can contain variable names and expressions (delimited with //)
which can be evaluated at run-time. For example, if aboutmsg.txt contained :

Laser Demo Application
By Dele Olajide

//Memory(0)//K bytes free

then ExpandText function can be used to obtain the exact amount of memory
available at run time with :

cMess = ExpandText (GetPointer (aboutmsg))

@@ ARRAY

ARRAY Resource

The Array resource provides the means of including user-defined resources. This
resource includes the user-specified array into the application.

The array can be nested and of any size. It is loaded into VMM by DBTALK when
the application begins. It is directly accessible in the application by name.

It can be used to reduce the amount of code required for setting up tables and
data structures like menus and reports.

The user must write a 'resource tool' program which will create/maintain the
resource in array form. This program must create the array file in the ARRTOSTR
format with extension 'ARR'. For example.

FUNCTION main

#DEFINE HELP    28
#DEFINE K_ESC   27
#DEFINE K_DOWN  24
#DEFINE K_UP    5
#DEFINE K_RIGHT 4
#DEFINE K_LEFT  19
#DEFINE K_HOME  1
#DEFINE K_END   6
#DEFINE K_PGUP  18
#DEFINE K_PGDN  3

   PRIVATE mtext   := {"File",  "Nominal", "Sales","Purchase", "Inventory",
"Reports", "Activity"}
   PRIVATE mkey    := { 289,     305,       287,    281,        279,
275,     286}

   PRIVATE mt1:= {"Accounts", "Customer", "Supplier", "Product", "Company",
"Exit"}
   PRIVATE mk1:= {1001,        1002,       1003,       1004,      1005,
K_ESC}

   PRIVATE mt2:= {"Enter Transactions", "Print Journals", "Print Details",
"Post Transactions", "Trial Balance",  "List of Accounts"}
   PRIVATE mk2:= {1011,                  1012,            1013,
1014,               1015,              1016}

   PRIVATE mt3:= {"Enter Sales", "Print Journals", "Post Transactions"}
   PRIVATE mk3:= {1021,                  1022,            1023}

   PRIVATE mt4:= {"Enter Purchases", "Enter Cheques", "Print Cheques", "Print
Journals", "Post Transactions"}
   PRIVATE mk4:= {1031,                  1032,            1033,
1034,               1035}

   PRIVATE mt5:= {"Adjust Stock", "Print Journals", "Post Transactions"}
   PRIVATE mk5:= {1041,                  1042,            1043}

   PRIVATE mt6:= {"Financial Reports", "Debtor Analysis", "Cash Flow", "Product
List", "Stock Activity",  "Stock Alert"}
   PRIVATE mk6:= {1051,                  1052,            1053,
1054,               1055,              1056}

   PRIVATE mt7:= {"End Month Process", "End Year Process"}
   PRIVATE mk7:= {1061,                  1062}

   PRIVATE aMenu , cMenu, nOut

   aMenu = {'DbEasy Accounting System',mtext,mkey, ;
            {mt1,mt2,mt3,mt4,mt5,mt6,mt7},;
            {mk1,mk2,mk3,mk4,mk5,mk6,mk7} }

   cMenu = arrtostr (aMenu)
   nOut = FCREATE ('EAMENU.ARR')
   FWRITE(nOut, cMenu)
   FCLOSE (nOut)
   RETURN

creates an array file EAMENU.ARR which contains the menu structure for the
DBEASY demo program. To use the menu structure in the application simply
involves :

ARRAY eamenu
....
oScr:Send('AttachMenu', eamenu)

and this makes the code much easier to maintain.

This feature makes it possible for DBTALK users to create their own classes and
any resource tools required for the class.

@@ ICON

ICON Resource

The icon resource is used to support the screen
resource. Icons referenced in a screen are not stored
in the screen file. The icon resource is use to put
the icon bitmap into an application or reusable object
file.

To use an icon in an application, the ICON compiler
directive is used to cause the resource compiler to
include the icon file in the compilation. For Example
:

ICON stop

will include the file 'STOP.ICN' in the compilation.

@@ BITMAP

BITMAP Resource

The bitmap resource is used to support the screen
resource. Bitmap graphics referenced in a screen are
not stored in the screen file. The bitmap resource is
use to put the bitmap file into an application or
reusable object file.

Bitmaps in DB-TALK are stored in an internal format
compatible with Clipper character strings. The Gforce
conversion utility PCX2BMP is supplied with DB-TALK to
take a PCX format file and convert it to Gforce BMP
format.

To use an bitmap in an application, the BITMAP
compiler directive is used to cause the resource
compiler to include the bitmap file in the
compilation. For Example :

BITMAP MAP

will include the file 'STOP.BMP' in the compilation.

@@ VECTOR

VECTOR Resource

The vector resource is used to support the screen
resource. Vector graphics referenced in a screen are
not stored in the screen file. The vector resource is
use to put the vector file into an application or
reusable object file.

Vectors in DB-TALK are stored in an internal format
compatible with Clipper character strings. A
conversion utility HPTOVEC is supplied with DB-TALK to
take a HP plot file and convert it to Dbtalk VEC
format.

HP plot files can be produced from any of the popular
drawing packages like Freelance or Draft Choice by
selecting an HP plotter as the device  and plotting to
a disk file.

To use an vector in an application, the VECTOR
compiler directive is used to cause the resource
compiler to include the vector file in the
compilation. For Example :

VECTOR WORLDMAP

will include the file 'WORLDMAP.VEC' in the
compilation.

@@ FONT

FONT Resource

The font resource allows font styles to be used in an
application. This allows custom fonts to display
special symbols, foreign language characters in non
standard alphabets or custom graphic characters.

To use a font in an application, the FONT compiler
directive is used to cause the resource compiler to
include the font file in the compilation. For Example
:

FONT SANSERIF

will include the file 'SANSERIF.FNT' in the
compilation.

@@CURSOR

There is no provision for user-defined cursors in
dbtalk. However the graphic cursor can be changed with
the following functions :

    mse_wait()   - Time/wait cursor

    mse_arrow()  - pointer cursor

    mse_ibeam()  - Text cursor

    mse_cross()  - cross cursor

@@ HELP

HELP Resource

The help resource is a simple way of providing up to
100 help screens within an application. There can be
only one help resource in an application.

DB-TALK does not provide a Help engine. However using
the help resource, a developer can store up to 100
help pages which can be recalled in DB-TALK screen
with the HelpText function. For example to provide
help in a program when the F1 key is pressed :

#DEFINE HELP 28
SCREEN helpscr
HELP   helptext
....
FUNCTION Main
......
oHelpScr = ADLClass ('SCN', helpscr)
.....

FUNCTION handle
PARAMETER nEvent
.....
  CASE nEvent = CHOICE1
       cHelpText = HelpText(1)

  CASE nEvent = CHOICE2
       cHelpText = HelpText(2)

  CASE nEvent = HELP
       oHelpScr:Send('Display)
       oHelpScr:Send('Wait')
       oHelpScr:Send('Clear')

In this program, screen Helpscr contains a multi-line
text box cHelpText which will display context
sensitive help. When user choice CHOICE1 is selected,
context is set to Help page 1, when CHOICE2 is
selected, context is set to page 2. When HELP is
selected (F1 pressed), help screen pops up showing
what ever help context is set.

HELPTEXT.HLP is a text file is in the following
format:

        <header> (this text which is ingored by
Resource Compiler)
        <delimiter line>
        <block of help text>
        <delimiter line>
        <block of help text>
        .
        .
        .
Delimiter lines have the following format:
        /nn <comment>

where "/" is the first character on the line and "nn"
is a two digit ascii number. The comment is optional.

@@Messages

ADL Class Library Messages

This chapter describes the messages that a program can
send to a DB-TALK object. Objects are created with :

   oScrnObject = ADLClass ('SCN', scrnfile)

where scrnfile is a resource included in the
application. In this example, scrnfile is created from
the file 'SCRNFILE.SCN' which in turn was produced by
'SCRNEDIT.EXE', the screen editor tool.

oScrnObject is passed messages using the send operator
like this:

   xResponse = oScrnObject:Send(cMessage,
xPara1,....xParaN)

cMessage is the message, xPara1.. xParaN are extra
values needed to support the message. xResponse is a
value returned by the method which handles the
message. For example :

   oLaserScrn:Send('Display', sanserif)

causes the 'Display' message to be passed to screen
object oLaserScrn with addition information that it
should use font resource sanserif. The value returned
should be discarded as it is of no interest to the
program.

The notation adopted is to prefix each variable with a
letter which indicates its type :

n    Numeric
c    Character/String
d    Date
l    Logigal
b    Code Block
x    Any type
ax   Array of type x

@@ Display

Display

Purpose

This message causes the screen to be painted with the
controls defined in the screen object. All data fields
will present their current stored values.

Syntax

oScrnObject:Send( 'Display', [cFont])

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class, cFont is an optional font file
resource. If it is not specified, the screen is
displayed in the default system resource.

Example

     oLaserScrn:Send('Display', sanserif)

@@ Read

Read

Purpose

This message causes the system to wait until the user
activates any of the controls defined on the screen
object. The event number of the control is returned.
It is used for procedural handling of events.

Syntax

oScrnObject:Send( 'Read')

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class.

Example

     nEvent = oLaserScrn:Send('Read')

     DO WHILE .T.
        DO CASE
        CASE nEvent = 27
             IF YesNoBox ('Warning', 'Do you wish to Quit')
                Quit()
             ENDIF

        CASE nEvent = ??
        .......
        ENDCASE
        nEvent = oLaserScrn:Send('Read')
     ENDDO

@@ Wait

Wait

Purpose

This message causes the system to wait until the user
activates a specific control defined on the screen
object or event ESC is received. All other control
activated by the user are dealt with first by the
system handler and then the screen handlers. It is
used for data-driven handling of events.

Syntax

nEvent1 = oScrnObject:Send( 'Wait', [nEvent2])

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class. nEvent2 is the button id or keyboard
code of the event that will terminate the interaction.
If it is omitted, code 27 (escape) is assumed. nEvent1
is the event that actually terminates the interaction.

Example

     nEvent = oLaserScrn:Send('Wait')
     nEvent = oLaserScrn:Send('Clear')
     ....

     FUNCTION handle
     PARAMETER nEvent
        IF nEvent = 27     // system handler
           IF YesNoBox ('Warning', 'Do you wish to Quit')
              Quit()
           ENDIF
        ENDIF
     RETURN nEvent        // pass on to screen handler


     FUNCTION Click
     PARAMETER nEvent    // screen handler
        IF nEvent = ??
        .......
        ENDIF
     ENDDO

@@ Refresh

Refresh

Purpose

This message causes the data entry screen controls to
be updated with their current values.

Syntax

oScrnObject:Send( 'Refresh')

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class.

Example

Refresh

     oLaserScrn:Send('Refresh')

@@ Attributes

Attributes

Purpose

This message is used to retrieve the attributes of a
screen button control into an array. This allows other
classes or functions to access a screen button control
without hard coding its dimensions. An example of this
can be seen in the charting class.

Syntax

aButton = oScrnObject:Send( 'Attributes', nButtonId)

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class. nButtonId is the event number defined
for the button by the screen editor. aButton is an
array containing the following information :

1. Control Type : value Bn where n is the button
    type.
                   1. Mommentary
                   2. Alternate
                   3. Indicator
                   4. Invisible
                   5. Radio
                   6. CheckBox

2. Top left corner X co-ordinate

3. Top left corner Y co-ordinate

4. Bottom right corner X co-ordinate

5. Bottom right corner Y co-ordinate

6. Width

7. Height

8. Foreground Colour

9. Background Colour

10.Botton text

11.Botton Event no

12.Button Control Type of 1 above in numeric

13.Internal Button Id number

Example

     aMap = oMapScrn:Send('Attributes', MAP)
     VDOBUTTON (aMap[13])      // simulate button press

@@ Object

Object

Purpose

This message is used to retrieve the generated FLD
object data entry field of a screen. This allows other
classes or functions to access a screen data entry
controls without hard coding its attributes.

Syntax

oField = oScrnObject:Send( 'Object', cFieldName)

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class. cFieldname is the field name defined
for the data entry field by the screen editor. oField
is a FLD object which can respond to the following
messages.

EDIT    : Force immediate data entry of field

REFRESH : Force immediate screen refresh of the data
           entry field.

PICK    : Use standard pickbox dialog box to be used
           to selecting a value from an array into the
           field.

Example

     oCity = oMapScrn:Send('Object', 'CITY')
     oCity:Send('Pick', {'Britain', 'France', 'USA'} )

@@ Clear

Clear

Purpose

This message causes the screen to be cleared and all
controls defined in the screen object removed.

Syntax

oScrnObject:Send( 'Clear')

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class.

Example

     oLaserScrn:Send('Clear')

@@ AttachFilters

AttachFilters

Purpose

This message causes the events for a screen to be sent
to specific screen handling routines instead of the
default global screen handlers. When a user interacts
with any DBTALK screen, data entry events are first
sent to the system handler 'HANDLE' then sent to the
screen handle routines 'SELECT' and 'UNSELECT'. Action
button events are sent to a different routine 'CLICK'.
The developer can choose which routine should handle
the event. However, if there is a need to have a
sparate handle routine for a specific screen, then
this message can be issued.

Syntax

oScrnObject:Send( 'AttachFilters', cSelectRtn,
cDeSelectRtn, cClick)

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class. cSelectRtn is the selection routine.
When a user selects a data entry field in this screen,
this function is given control. cDeSelectRtn is the
deselection routine. When the user finishes data entry
of a field, this routine is given control. cClick is
the action button routine. When any action button is
clicked, this routine is given control.

Example

     oLaserScrn:Send('AttachFilters', 'SelFld', 'DeSelFld',
     'Perform')
     ....
     FUNCTION SelFld
     PARAMETER cFld, oFld, oScrn
     PRIVATE lSelect:=.T.
     .....
     RETURN lSelect


     FUNCTION DeSelFld
     PARAMETER cFld, oFld, oScrn
     PRIVATE lValid:=.T.
     .....
     RETURN lValid

     FUNCTION Perform
     PARAMETER nEvent, oScrn

     IF nEvent = CHOICE1
     .....

@@ AttachMenu

AttachMenu

Purpose

This message causes the system menu to be associated
with a screen object. When this screen object is being
read, a user can activate the system pull-down menu.

Syntax

oScrnObject:Send( 'AttachMenu', aMenuSpec)

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class. aMenuSpec is an array of the following
five data types:

cMenuTitle   : This text will appear above the menu
                bar as the title of the application.

aPrompts     : This is an array consisting of the
                main menu options that will apear on
                the menu bar.

aPromptNos   : This is an array of event numbers that
                the menu prompts will activate.

aPullPrompts : This is a two-dimensional array
                containing the pull-down prompts for
                all the prompts on the menu bar.

aPullNos     : This is a two dimensional array
                containing the event numbers for the
                pulldown prompts.

Example

     PRIVATE mtext   := {"File",  "Edit", "About"}
     PRIVATE mkey    := { 289,     274,   286}
     PRIVATE mfile_t := {{"Browse", "Chart", "Report",
     "Exit"}, {"Next","Previous"}, {"About"}}
     PRIVATE mfile_k := {{BROWSE, CATEGORY, REPORT,
     K_ESC},{K_RIGHT, K_LEFT}, {ABOUT}}

     oLaserScrn  = ADLClass('SCN', laserscr)

     oLaserScrn:Send('AttachMenu', {'Laser Disk Collection
     System',mtext,mkey,mfile_t,mfile_k})
     oLaserScrn:Send('Bar')

@@ Bar

Bar

Purpose

This message causes the system menu attached to the
screen object to be displayed and activated.

Syntax

oScrnObject:Send( 'Bar')

Comments

oScrnObject is a screen object created with the 'SCN'
built-in class.

Example

     oLaserScrn:Send('Bar')

@@Database

Database Messages

The database messages follow syntax and are all based
on the CLIPPER DML (Data Manipulation Language). The
syntax is

xResponse = oDbView:Send('DML command', cAlias,
xPara1.... xParaN)

xResponse is the response from the DML command.
oDbView is a DB-TALK database view object created with
the ADL Class 'DBF'. cAlias is the alias defined for
the database file to be accessed and xPara1....xParaN
are the additional values needed by the DML command.
For example :

lEofIndicator = oLaserView:Send('EOF', 'LASER')

Returns TRUE if end of file is reached on the
LASER.DBF file.

The DML commands are as follows :

OPEN

To open a database view, opening all database files
and indexes. Setting up all relationships and filters.

READ

To copy the values of fields defined in the database
view from the selected database file to memory
variables with the same name.

WRITE

To replace the values of fields defined in the
database view from memory variables with the same
name.

PICK

To position the database through the use of the
standard browsebox dialog box.

BOF

To determine whether the record pointer is located at
the beginning of the current database file

APPEND

To append a blank record to the current database file

COMMIT

To flush all buffered changes to disk.

DELETE

To mark current record for deletion.

GOBOTTOM

To position record pointer to the last record in the
database file.

GOTO

To position record pointer to a specific record in the
database file.

RECALL

To undelete a record marked for deletion.

REINDEX

To refresh an opened index.

SEEK

To locate records in a database file using an index
file.

SELECTAREA

To select a work area.

SETORDER

To change the master index to another opened index
file.

SKIP

To move the record pointer relative to the current
record

STRUCT

To create an array containing the structure of the
current database file

UNLOCKALL

To release all record and file locks in all work
areas.

DELETED

To find out if current record is deleted

EOF

To determine whether the record pointer is located at
the end of the current database file

FCOUNT

To determine the number of fields in a data file.

FLOCK

To attempt to lock the current database file so that
no other users can write to the file.

FOUND

To determine whether database record access was
successful.

LASTREC

To determine the number of records in a database file.

LOCK

To attempt to secure a record lock on a network.

NETERR

To determine whether an 'OPEN' or 'APPEND' has failed
on a network.

RECNO

To determine the value of the database record pointer

RECSIZE

To determine the record size of the current database
file

@@Reporting

Reporting Messages

One of the principles of Object-oriented designs is
not to duplicate functionally. Word Processing
programs, spreadsheets and DTP programs are the best
means of presenting information on paper.

Applications in DB-TALK are not supposed to
communicate directly with printers. It is pointless
duplicating a lot programming that is much more better
done in a word processor.

DB-TALK provides a WP class which allows WP documents
to created within a DB-TALK application under program
control. DB-TALK provides for full control on the
presentation and document layout.

In addition, DB-TALK provides a report writer which
can be used to simplify report writing . The report
writer can be used for columnar reports that produce
totals. Up to two levels of grouping can be handled.

@@ OPEN

OPEN

Purpose

Creates a new WP document. An standard template
(Manuscript only) can be used to provide global
settings. In the case of 1-2-3, the column and row
indicators are set to 1.

Syntax

oWpDoc = ADLClass ('WP' {cWpType, cDocFile, cTemplate}
)
....
oWpDoc:Send ('Open')

Comments

oWpDoc is the WP object created. cWPType is an
identifier of document format. Accepted values are :

'WP'  - Word Perfect
'MS'  - Lotus Manuscript
'123' - Lotus 1-2-3
cDocFile is the document file name and cTemplate is an
existing WP document file which will be used as the
template document.

Example

     oLaserWp = ADLClass ('WP', {'WP', 'laser.wp5', ''} )

     oLaserWp:Send('Open')

@@ ADD

ADD

Purpose

Writes a block of text to the WP document object. In
the case of 1-2-3, cText can be of any type and is
written to the current cell. The column indicator is
then advanced.

Syntax

oWpDoc:Send ('Add', cText, [nRow, nCol])

Comments

oWpDoc is the WP object created. cText is the text to
be added. For Lotus 1-2-3, nRow and nCol are the new
row and column positions.

Example

     oLaserWp:Send('Add', 'This is a smaple text')

@@ ADDLINE

ADDLINE

Purpose

Writes a complete paragraph to the WP document object.
In the case of 1-2-3, cText can be of any type and the
value is put into the current cell. The row indicator
is advanced and the column indicator is set to 1.

Syntax

oWpDoc:Send ('AddLine', cText)

Comments

oWpDoc is the WP object created. cText is the text to
be added.

Example

     TEXT intro
     .....
     oLaserWp:Send('AddLine', intro)

@@ NEWPAGE

NEWPAGE

Purpose

Inserts a new page formatting code into the WP
document

Syntax

oWpDoc:Send ('NewPage')

Comments

oWpDoc is the WP object created.

Example

     oLaserWp:Send('NewPage')

@@ CLOSE

CLOSE

Purpose

Closes the WP document

Syntax

oWpDoc:Send ('Close')

Comments

oWpDoc is the WP object created.

Example

     oLaserWp:Send('Close')

@@ INITIATE

INITIATE

Purpose

To start a report generation. Print headings and
initialise totals.

Syntax

oRep = ADLClass ('REP', {nReport, oDevice, cHeading} )
oRep:Send ('Initiate')

Comments

oRep is the REP object created. nReport is a report
resource. oDevice is a WP document object or any other
object that will respond to 'Open', 'Add', 'Addline'
and 'Close' messages. cHeading is an optional heading
text.

Example

     REPORT samplerep
     .....
     oWpDoc = ADLClass ('WP', {'WP', 'laser.wp5', ''} )
     oRep   = ADLClass ('REP', {samlerep, oWpDoc, ''} )

     oWpDoc:Send('Open')
     oRep:Send ('Initiate')

@@ GENERATE

GENERATE

Purpose

To generate a detail line from a report. Total lines
if applicable will be produced as well.

Syntax

oRep:Send ('Generate')

Comments

oRep is the REP object created.

Example

     REPORT samplerep
     .....
     oWpDoc = ADLClass ('WP', {'WP', 'laser.wp5', ''} )
     oRep   = ADLClass ('REP', {samlerep, oWpDoc, ''} )

     oWpDoc:Send('Open')
     oRep:Send ('Initiate')
     oDbView:Send('GoTop', 'TEST')

     DO WHILE ! oDbView:Send('Eof', 'TEST')
        oRep:Send ('generate')

@@ TERMINATE

TERMINATE

Purpose

To finish a report. The grand total line if applicable
will be produced as well.

Syntax

oRep:Send ('Terminate')

Comments

oRep is the REP object created.

Example

     REPORT samplerep
     .....
     oWpDoc = ADLClass ('WP', {'WP', 'laser.wp5', ''} )
     oRep   = ADLClass ('REP', {samlerep, oWpDoc, ''} )

     oWpDoc:Send('Open')
     oRep:Send ('Initiate')
     oDbView:Send('GoTop', 'TEST')

     DO WHILE ! oDbView:Send('Eof', 'TEST')
        oRep:Send ('generate')
        oDbView:Send('Skip', 'TEST', 1)
     ENDDO

     oRep:Send ('Terminate')
     oWpDoc:Send('Close')

@@Charting

Charting

DB-TALK provides a simple means of producing line
charts, 2D bar charts and 3D bar charts. In addition,
hard-copies of the chart can be produced for insertion
into a WP document through Lotus PIC files which can
be read by both the supported Word Perfect and Lotus
Manuscript formats.

LINECHART

Purpose

Produces a line chart.

Syntax

oChart = ADLClass ('CHT' {aChart, cTitle, bValues,
aXaxis} )
....
oChart:Send ('LineChart', [cPicFile])

Comments

oChart is the CHT object created. aChart is a SCN
button control array which defines the screen control
to which the chart is associated. cTitle is the title
of the chart. bValues is codeblock that returns an
array containing the values to be plotted. aXaxis is
an array of labels for the xaxis. cPicfile is an
optional and is the name of the PIC file to be
generated from the chart. If omitted, no PIC file will
be produced.

Example

     EXTERNAL Chart

     FUNCTION Main
     PRIVATE bValues:={|| aPlotValues}
     PRIVATE aXaxis = {'One', 'Two', 'Three'}
     ....
     aChart = oScrn:Send('Attributes', 15)
     aPlotvalues = {1,2,3}

     oChart = ADLClass ('CHT' {aChart, 'Sample Plot',
     bValues, aXaxis} )
     ....
     oChart:Send ('LineChart', 'line.pic')

@@ 2DCHART

2DCHART

Purpose

Produces a 2D bar chart.

Syntax

oChart:Send ('2DChart', [cPicFile])

Comments

oChart is the CHT object created. cPicfile is an
optional and is the name of the PIC file to be
generated from the chart. If omitted, no PIC file will
be produced.

Example

     EXTERNAL Chart

     FUNCTION Main
     PRIVATE bValues:={|| aPlotValues}
     PRIVATE aXaxis = {'One', 'Two', 'Three'}
     ....
     aChart = oScrn:Send('Attributes', 15)
     aPlotvalues = {1,2,3}

     oChart = ADLClass ('CHT' {aChart, 'Sample Plot',
     bValues, aXaxis} )
     ....
     oChart:Send ('2DChart', '2dchart.pic')

@@ 3DCHART

3DCHART

Purpose

Produces a 3D bar chart.

Syntax

oChart:Send ('3DChart', [cPicFile])

Comments

oChart is the CHT object created. cPicfile is an
optional and is the name of the PIC file to be
generated from the chart. If omitted, no PIC file will
be produced.

Example

     EXTERNAL Chart

     FUNCTION Main
     PRIVATE bValues:={|| aPlotValues}
     PRIVATE aXaxis = {'One', 'Two', 'Three'}
     ....
     aChart = oScrn:Send('Attributes', 15)
     aPlotvalues = {1,2,3}

     oChart = ADLClass ('CHT' {aChart, 'Sample Plot',
     bValues, aXaxis} )
     ....
     oChart:Send ('3DChart', '2dchart.pic')

@@SCRNEDIT

SCRNEDIT - The Screen Editor

To edit a screen, type

SCRNEDIT <file name>

at the DOS prompt.

File menu

OPEN : Select screen file to edit

SAVE : Enter File name of current screen (NO
extension)

NEW :  Clears the current screen design

IMPORT : Append a reuseable screen file to the
          current screen design

GENERATE : Creates a .PIC file from the current screen

Edit Menu

CLEAR ALL : Removes all drawn objects

UNDRAW : Remove last drawn object

REFRESH : Redraw screen

TEST MODE : Make buttons active to test Event number
(ESC terminates)

EDIT MODE : Select object by clicking on it with left
button or TAB/SHIFT TAB  keys.

To select an object in edit mode click on the object
directly, however if it is already overlapped by a
bigger object, then that object will always be
selected. Use the TAB/SHIFT TAB keys to select next
and previous objects.

DEL key removes a selected object.

To copy a screen object in EDIT mode press INS key.

Use CNTRL key while holding down left  mouse btton to
drag object to new position.

Right button click on selected  object will bring up
properties dialog box. Any of the 12 values can be
modified by clicking directly on value.

Frames

RAISED FRAME : Hold down left mouse button and drag
botton right corner to  desired position for raised
frame.

SUKEN FRAME : Just like raised frame.

Buttons

Just like frames use mouse to position and size
button. Enter button label and   the event number for
the button. For Radio/Check boxes, enter bit field
name  and bit number.

Fields

USE DATABASE : Select DBF file for field names.

FIELDS : Draw field like buttons/frames and enter
field name and optional  picture. Data Entry fields
are supported in four display types. An optional
picture clause can be specified. They are
automatically snapped onto an invisible 27 by 80 grid
for VGA text font redefinition support.

Draw

Draw Lines, rectangles, filled rectangles, Circles
Icons, Text, Bitmaps and  Vector images. Vector files
in 'VEC' format are supported. A separate utility
'HPTOVEC' is provided to convert a HP plot file into
VEC format. Another utility ICO2ICN can be used to
convert any WINDOWS icon into DBTALK format.

Colors

TEXT : Current text foreground color

TEXT BK : Current text background color

DRAWING : Current color for draw objects.

BUTTON : Current button color

SCREEN : Screen backgound color (not saved in screen
file) PALETTE : Select a VGA palatte file (not saved
in screen file) FONT : Select a FONT file (not saved
in screen file)

Fonts & VGA palettes can be previewed with the screens
that will use them.

@@DBU Tool

DBU The Database Utility

DBU is supplied with DB-TALK as a tool for maintaing a
database view resource.

The main screen shows up to six columns, each of which
represents a select area.  One unused column is
visible unless all six are being used.  Each active
column contains the name of a data file, a list of
open index files, and an active fields list.  The
items on this screen together with relations and
filters make up the current View which affects all
system operations. The View can be saved in a disk
file and restored at a later time.

Help is provided by pressing the F1 key.

@@TOOLS

In addition to SCRNEDIT and DBU a number of other
resource tools are provided.

ICON

This is the icon editor. To edit an icon type :

   ICON [icn file]

If the icon file is omitted, a blank screen is
presented.

FONT

This is the font editor. To edit a font type :

   FONT [fnt file]

If the font file is omitted, a blank screen is
presented.

ICO2ICN

This utility will convert WINDOWS 'ICO' files into
Gforce 'ICN' format for use by DBTALK programs. Use
as:

   ICO2ICN <ico file spec>

For example to convert all ico files in directory test
to icn type ICO2ICN *.ico

HPTOVEC

This utility will convert HP plot files into VEC
vector format for use by the screen editor. Use as:

   HPTOVEC <HP plot file>

@@Functions

Clipper Functions

DB-TALK is written in Clipper and relies heavily on
the excellent Clipper run-time engine to be able to
interpret its own functions which call the basic
Clipper primitive functions. To keep the run time
engine compact only Clipper functions used by DB-TALK
can be accessed.

The documentation of these Clipper functions is beyond
the scope of this guide. A good book to read is the
CLIPPER Programmer's reference by W. Edward Tiley. It
has everything you may wish to know about CLIPPER
normal functions you may freely use and the primitives
which you are advised not to use. The ones accessible
from DB-TALK are referenced below.

@@ Arrays

Arrays

DB-TALK supports the new multi-dimension array data
structure of Clipper 5. Calling this data structure an
array is a misnomer. It is in-fact powerful list
structure which can be used to represent almost any
type of data structure required.

AADD

To add new elements to an array

aadd (aArray, xExpr)

ACOPY

To copy the elements of one array into another array

acopy (aSource, aTarget, [nStart], [nCount],
[nTargetPos])

ADEL

To delete any single element from an array

adel (aTarget, nPos)

DIRECTORY

To create an array that contains the directory
information of a specification of files and file
attributes

aArray = directory (cDirSpec, cAttributes)

AEVAL

To navigate an array evaluating a code block on each
element found.

aeval (aArray, bBlock, [nStart, nCount])

AFILL

To fill selected elements of ann array with a
specified value

afill (aTarget, xExpr, [nStart, nCount])

AINS

To insert an element into an array at a specified
location. All other elements are pushed forward

ains (aTargetm nPos)

ARRAY

To create an array.

aArray = array (aLength)

ASCAN

To search an array for the first element that matches
an expression.

ascan (aTarget, xExpr, [nStart, nCount])

ASIZE

To re-size an array after creation.

asize (aTarget, nLength)

ASKIP

To navigate an array and return the actual number of
elements skipped.

nSkip = askip (aArray, nElemetPos, nSkip)

ASORT

To sort selected elements of an array in ascending
order.

asort (aTarget, [nStart], [nCount])

LEN

To determine the number of elements in an array

nSize = len (aArray)

@@ DOS Files

DOS Files

One of the strength's of Clipper is that it provides
basic functions to manipulate any type of DOS file.
DB-TALK provides additional support by providing
functions to read and write lines of ASCII text files.

FREADLN

To read an ASCII text line

lEof_flag = freadln ( nHandle, @cBuffer, nMax_line)

WRITELN

To write an ASCII text line

fwriteln ( nHandle, cBuffer)

FCLOSE

To close a DOS file

fclose ( nHandle)

FCREATE

To create a DOS file

nHandle = fcreate ( cFileName, nAttribute)

FERROR

To determine what errors have occured by a low-level
DOS file funnction

nErrorNumber = ferror ()

FILE

To determine the existence what errors have occured by
a low-level DOS file funnction

nErrorNumber = ferror ()

FOPEN

To open a DOS file

nHandle = fopen ( cFileName, nAttribute)

FREAD

To read a number of bytes from an opened DOS file

nBytes_read = fread ( nHandle, @cBuffer, nBytes)

FRENAME

To rename a DOS file name

FreName (cOldName, cNewName)

FSEEK

To position the DOS file pointer

fseek ( nHandle, nOffset, [nStartIndicator]))

FWRITE

To write a number of bytes to an opened DOS file

fwrite ( nHandle, cBuffer, nBytes)

@@ Environment

Environment

Clipper uses a number of environmental functions to
control its behaviour and to provide memory, keyboard,
screen and file services. DB-TALK allows access to
these functions and provides further functions to
service DB-TALK objects.

QOUT

To display data on the current display device with a
line feed.

qout (xExpr)

QQOUT

To display data on the current display device without
a line feed.

qqout (xExpr)

QUIT

To return back to DOS after closing all open files

quit ()

KEYBOARD

To clear out or stuff the 'type-ahead' keyboard buffer
with character.

keyboard ([cTypeAheadCharacters])

KILL

To remove a PUBLIC variable from memory

kill (cVarName)

SET

To determine the status of or change the status of
various CLIPPER environment control variables.

set (nSelection, xNewsetting, [cFileName])

COL

To return the current screen column position

nColumn = col()

CURDIR

To determine the current DOS directory

cDir = curdir(cDiskDrive)

DISKSPACE

To determine the amount of disk space left on disk

nSpaceLeft = diskspace (nDriveNumber)

DOSERROR

To determine if any program action has caused a DOS
error

nErrorCode = doserror()

ERRORLEVEL

To determine or set the DOS errorlevel

nErrorLevel = errorlevel ([nNewErrorLevel])

GETE

To import the contents of a DOS environment variable

cExpr = getenv (cVarName)

INKEYWAIT

To obtain the next keystroke.

cCharacter = inkeywait (nNoSecs)

LASTKEY

To determine the last keystroke.

cCharacter = lastkey ()

MEMORY

To determine the amount of memory left

nBytesLeft = memory (nTypeQuery)

NEXTKEY

To inspect the keyboard buffer to determine the next
keystroke.

cCharacter = nextkey()

SETCANCEL

To determine or inhibit the use of ALT-C as a means of
terminating an application

lCurrentStatus = setcancel ([lNewStatus])

SETCOLOR

To determine the current color setting or define new
setting

cCurrentColor = setcolor ([cNewColor])

SETCURSOR

To determine the current cursor shape or define a new
shape

cCurrentShape = setcursor ([cNewShape])

SETKEY

To determine the current hotkey action or determine a
new action.

bCurrentAction = setkey ([nInkeyval], [bNewAction])

SETMODE

To change the display mode on an EGA/VGA display
adaptor.

lFlag = setmode (nRows, nCols)

SETTRACE

To put the DB-TALK trace mode on.

lOldstatus = settrace (lNewStatus)

TONE

To sound the PC speaker

tone (nFreq, nDuration)

@@ Numeric

Numeric Functions

In addition to the basic numeric operators, the
following Clipper numeric functions can be used to
provide further extend DB-TALK's computational
capabilities.

ABS

Absolute value of a numeric expression

nVal = abs (nExpr)

EXP

Derive natural antilogrithm of a number

nVal = exp (nExpr)

INT

Derive integer value of a number

nVal = int (nExpr)

LOG

Derive natural log of a number

nVal = log (nExpr)

MAX

Determine the greater of two values

lFlag = max (xEpr1, xExpr2)

MIN

Determine the smaller of two values

lFlag = max (xEpr1, xExpr2)

ROUND

Round a value up to a specific decimal precision

nVal = round (nExpr)

SQRT

Derive the square root of a number

nVal = sqrt (nExpr)

@@ String

String

In addition to the basic string operators, the
following Clipper string functions can be used to
further extend DB-TALK's text processing capabilities.

AT

Establish where a substring begins in a string

nPosition = at (cSubString, cString)

ALLTRIM

Remove leading and trailing spaces from a string

cVal = alltrim (cExpr)

LEFT

Extract a substring from a string starting from the
left

cVal = left (cExpr, nNoChars)

LEN

Establish how long a string is

nStringLength = len (cExpr)

LOWER

Translate all characters into lowercase

cVal = lower(cExpr)

LTRIM

Remove leading spaces from a string

cVal = ltrim (cExpr)

MEMOEDIT

Edit a string variable with a screen editor

cVal = memoedit(nTop, nLeft, nBot, nRight,
lEditMode,cUdf,nLineLen,nTabsize)

MEMOLINE

To extract and format text lines from a string/memo
variable

cVal = memoline (cString, nLinelen, nLineNo, nTabSize,
lWrap)

MEMOREAD

Read an ASCII file from disk into a string variable

cVal = memoread (cFileName)

MEMOTRAN

Translate hard returns and soft returns into alternate
characters

cVal = memotran (cString, cHardChar, cSoftChar)

MEMOWRIT

Create an ASCII file on disk from  a string variable

lFlag = memowrit (cFileName, cString)

MLCOUNT

Establish how many formatted text lines are in a
string/memo variable

nLines = mlcount (cString, nLinelen, nTabSize, lWrap)

MLPOS

Establish absolute position within a formatted string
of a line position

nNoChars = mlpos (cString, nLinelen, nLineNumber,
nTabSize, lWrap)

PAD PADL PADR

Pad a string variable with spaces.

cVal = pad (cString, nLength, cPadChar)

RAT

Establish where a substring begins in a string from
the rear

nPosition = rat (cSubString, cString)

REPLICATE

Repeat a character string many times

cVal = replicate (cString, nNoTimes)

RIGHT

Extract a substring from a string starting from the
rear

cVal = right (cExpr, nNoChars)

SPACE

Pad a string value with spaces

cVal = space (nSize)

STRTRAN

Search and replace of substrings within strings

cVal = strtran (cString, cSearch, cReplace, nStart,
nCount)

STUFF

Insert, modify and delete characters within a string

cVal = stuff (cString, nStart, nDelete, cInsert)

SUBSTR

Extract a substring from a string starting from any
point

cVal = substr (cExpr, nStart, [nNoChars])

TRIM

Remove trailing spaces from a string

cVal = trim (cExpr)

UPPER

Translate all characters into uppercase

cVal = upper(cExpr)

@@ Date

Date

In addition to the basic date operators, the following
Clipper date functions can be used to further extend
DB-TALK's date processing capabilities.

CDOW

Return name of day in week from a date

cDay = cdow (dExpr)

CMONTH

Return name of month from a date

cMonth = cmonth (dExpr)

DATE

Return system date

dCurrentDate = date()

DAY

Obtain day of month from a date

nDay = day (dExpr)

DOW

Obtain day of week from a date

nDay = dow (dExpr)

MONTH

Obtain day of month from a date

nDay = dow (dExpr)

SECONDS

Obtain no of seconds past since midnight

nSecs = seconds ()

TIME

Obtain current time

cTime = time()

YEAR

Obtain 4 digit year from a date

nYear = year (dExpr)

@@ Logical

Logical

In addition to the basic logical operators, the
following Clipper logical functions can be used to
further extend DB-TALK's logic processing
capabilities.

EMPTY

Confirm a variable does have a value of any type

lFlag = empty (xEpr)

IF/IIF

Achieve conditional assignment

xVal = iif (lCondition xTrueExpr, xFalseExpr)

ISALPHA

Determine if first characater of a string is aphabetic

lFlag = isalpha (cExpr)

ISCOLOR

Determine if computer can display colors

lFlag = iscolor ()

ISLOWER

Determine if first characater of a string is lowercase

lFlag = islower (cExpr)

ISPRINTER

Determine if printer is ready

lFlag = isprinter ()

ISUPPER

Determine if first characater of a string is uppercase

lFlag = isupper (cExpr)

@@ Conversions

Conversions

DB-TALK allows direct access to Clipper data type
conversion functions. The functions are as follows :

ASC

First character to ASCII

nAsciiVal = asc (cExpr)

BIN2I

16-bit signed to integer

nVal = bin2i (cSignedInt)

BIN2L

32-bit signed to integer

nVal = bin2l (cSignedInt)

BIN2W

64-bit signed to integer

nVal = bin2w (cSignedInt)

CHR

ASCII to single character

cCharacter = chr (nAsciiVal)

CTOD

Character to Date

dVal = ctod (cExpr)

DTOC

Date to Character

cVal = dtoc (dExpr)

DTOS

Date to Character (sort format)

cVal = dtos (dExpr)

I2BIN

Integer to 16-bit signed

cSignedInt = i2bin (nVal)

L2BIN

Integer to 32-bit signed

cSignedInt =l2bin (nVal)

STR

Numeric to string

cString = str (nVal, nNoDigits, nDecimals)

TRANSFORM

Convert any value into character using a picture
specification.

cString = transform (xExpr, cPictureSpec)

TYPE

Determine data type of expression

cDataType = type (xEpr)

VAL

String to Numeric

nVal = val (cExpr)

@@Timer

There is a single event timer that can be used to
process application logic during wait states. The
SeTimer (nCycles) function sets the number of times
the event handler will scan the mouse and keyboard.
Default is SetTimer(0) which means wait for event. For
an example, see the screen clock in the demo
application.

@@BIT STRING

Bit String Functions

To test if a bit is set on

     lOn = BitTest(cBitString, nPosition)

To set a bit on

     cNewString = BitSet(cBitString, nPostion)

To set a bit off

     cNewString = BitReset(cBitString, nPosition)

@@Picture

PICTURE CODES

A picture specification consists of  FUNCTION codes,
PICTURE template codes, or a combination of both.

If FUNCTION codes are used, they appear first. As many
FUNCTION codes as desired may be included with no
embedded spaces.  The last FUNCTION code in the string
must be followed by one or more spaces.  The space(s)
signals the end of the FUNCTION codes and the start of
the PICTURE template codes.  The available FUNCTION
and PICTURE template codes are listed as follows

FUNCTION Codes

A -- Allow alphabetic characters only.

B -- Left-justify numeric data within the output
field.

C -- A CR (credit) is displayed after a positive
number.  May be used with numeric data only.  May be
used with the SAY clause only.

D -- Uses the current SET DATE format (e.g. BRITISH,
GERMAN, etc.) for editing date type data.

E -- Edit date type data as a European (BRITISH)
date.

K -- Erase current value if first key is not a cursor
key

R -- Non-template characters will be displayed but not
stored in the variable.  May be used with character
data only.

S<n> -- Limit display width to <n> characters, where
<n> is a positive integer.  Horizontally scroll the
field within the <n> columns specified.  The Right
Arrow, Left Arrow, Home and End cursor-control keys
may be used to bring hidden portions of the field into
view.  May be used with character data only.

X -- A DB (debit) symbol is displayed after negative
numbers.  May be used with numeric data only.  May be
used with the SAY clause only.

Z -- The field is displayed as all blanks if its
numeric value is 0.  May be used with numeric data
only.

( -- Negative numbers are enclosed in parentheses when
this function is used.  May be used with numeric data
only.  May be used with the SAY clause only.

! -- Any character may be entered; however, alphabetic
characters will be converted to uppercase.  May be
used with character data only.

PICTURE Template Codes

A PICTURE expression may include any desired
characters; only those characters listed below
actively participate in editing and data entry.  If
any other characters are included in the format, they
appear in output and, for input operations, appear in
the field as comment information which is skipped over
by the cursor.

The characters which may be used within the picture
expression are described below.

A -- Allows only alphabetic characters to be entered.

L -- Allows logical data only.

N -- Allows letters and digits only.

X -- Allows any character.

Y -- Allows logical Y, y, N, n only, converting y and
n to Y and N respectively.

9 -- With character data, allows digits only.  With
numeric data, allows digits and signs.

# -- Allows digits, blanks and signs.

! -- Converts lowercase letters to uppercase letters.

* -- Asterisks are displayed in front of the numeric
value.

. -- A period specifies the decimal point position.

, -- A comma may be used to separate digits left of
the decimal point.

@@SETS

SET Function Code values

The SET function can be used to alter certain default
parameters in the Clipper run-time engine. Format is :

xOldValue = SET (nCode, xNewValue)


nCode  Keyword     Data     Description
                   Type


1      EXACT       Logical  Specify method of
                            comparing strings

2      FIXED       Logical  Integers or decimals

3      DECIMALS    Numeric  Fix decimal precision

4      DATEFORMAT  Characte American    mm/dd/yy
                   r        ANSI        yy.mm.dd
                            British     dd/mm/yy
                            French      dd/mm/yy
                            German      dd.mm.yy
                            Italian     dd-mm-yy
                            Japan       yy/mm/dd
                            USA         mm-dd-yy

5      EPOCH       Numeric  Set Begining of century

6      PATH        Char     List of subdirectories
                            seperated by semicolons to
                            be used for reading files

7      DEFAULT     Char     Specify directory for
                            writing files

8      EXCLUSIVE   Logical  Set network usage of files

9      SOFTSEEK    Logical  Determine whether record
                            pointer is positioned at
                            next record or end of file
                            after a seek failure

10     UNIQUE      Logical  Surpress/Access records
                            with duplicate indexes

11     DELETED     Logical  Surpress/Access deleted
                            records

12     CANCEL      Logical  Inhibit/Allow use of ALT C
                            to terminate DB-TALK
                            applications

13     DEBUG       Logical  Switch on Clipper
                            debugging

14     TYPEAHEAD   Numeric  Fix typeahead buffer size

15     COLOR       Char     Set video color

16     CURSOR      Logical  Display/Hide cursor

17     CONSOLE     Logical  Inhibit/Allow screen
                            display

18     ALTERNATE   Logical  Re-direct screen display
                            to a file

19     ALTFILE     Char     Specify file to be used
                            for screen re-routing

20     DEVICE      Logical  Re-direct screen display
                            to screen or printer

23     PRINTER     Logical  Set printer on for printer
                            output

24     PRINTFILE   Char     Specify file to be used
                            for printer re-routing

25     MARGIN      Numeric  Set left margin for
                            printer output

26     BELL        Logical  Turn on/off speaker during
                            data entry

27     CONFIRM     Logical  Force pressing of return
                            key to complete each field
                            data entry

28     ESCAPE      Logical  Allow escape key to end
                            data entry

29     INSERT      Logical  Toggle Insert key between
                            insert and overtype

30     EXIT        Logical  Allow cursor keys to end
                            data entry

31     INTENSITY   Logical  Force the same color to be
                            used for both display and
                            data entry fileds

32     SCOREBOARD  Logical  Inhibit CLIPPER's use of
                            the top row for status
                            information

33     DELIMITERS  Logical  Allow/disallow use of
                            delimiters for data entry
                            fields

34     DELIMCHARS  Char     Set delimiter characters